Assembly Directive
You can use the Assembly directive to reference an external assembly from a template, or to include a source file for dynamic compilation. For example, CodeSmith Generator ships with an assembly named CodeSmith.CustomProperties.dll that includes custom editors for file names and string collections. If you'd like to use one of these editors from your own template's property sheet, you need to reference the assembly:
<%@ Assembly Name="CodeSmith.CustomProperties" %>
The source code for the CustomProperties assembly is in the Sample folder (E.G., Documents\CodeSmith Generator\Samples\<Version>\Projects\CSharp\CustomPropertiesSample) of your CodeSmith Generator installation.
There are two attributes that you can supply to the Assembly directive. You must supply one or the other, but not both.
Name
The Name attribute specifies the file name of an assembly to reference from the current template.
Path
The path attribute is a directory path to the assembly being used.
Src
The Src attribute specifies the relative path to a source file that should be dynamically compiled along with the template.
CodeTemplate Directive
Every CodeSmith template must start with a CodeTemplate directive.
The CodeTemplate directive is the only required directive and is used to specify the general properties of the template, such as the language that the template is written in and the description that will show in CodeSmith Explorer as a tooltip for the template. For example, here's the CodeTemplate directive from the VBSortedList.cst sample template:
<%@ CodeTemplate TargetLanguage="VB" Description="Generates a strongly-typed collection of key-and-value pairs that are sorted by the keys and are accessible by key and by index." %>
This directive specifies that the template uses Visual Basic .NET as its own code-behind language, and that it produces VB output. It also includes a description of the purpose of the template.
There are seven attributes that you can supply to the CodeTemplate directive. The Language parameter is required; all of the rest are optional.
Language
The Language attribute specifies what language will be used to write the template. Possible values for this attribute are:
- C# to author the template in C#
- JS to author the template in JScript
- VB to author the template in Visual Basic .NET
TargetLanguage
The TargetLanguage attribute is used to specify the output language of the template. You can use any string you like for the attribute; CodeSmith doesn't use it in any way to generate the template's output. This attribute is used by CodeSmith Explorer to determine which folder to display the template in when in template language view. CodeSmith also uses this attribute to determine how to syntax highlight the static content of a template.
Description
The Description attribute is used to describe your template in a general way. CodeSmith Explorer displays this description as a tooltip for the template.
Inherits
By default all CodeSmith templates inherit from \. This class provides the basic functionality of the template; much like the Page class provides the basic functionality of an ASP.NET page. The Inherits attribute can be used to specify that a template inherits from a different class. However, any class that a template inherits from must inherit, directly or indirectly, from CodeSmith.Engine.CodeTemplate. CodeSmith must also be able to find this class. To ensure this, you must supply an Assembly directive pointing to the assembly that contains the class, or a Src attribute that points to the source code for the class.
For an example of using template inheritance, see the CodeSmithBaseTemplates sample project included with your CodeSmith installation. This project defines two new template classes, OutputFileCodeTemplate which inherits directly from CodeTemplate and SqlCodeTemplate which inherits from OutputFileCodeTemplate. To base a new template on SqlCodeTemplate you could include these directives at the top of your template:
<%@ CodeTemplate Inherits="CodeSmith.BaseTemplates.SqlCodeTemplate" %> <%@ Assembly Name="CodeSmith.BaseTemplates" %>
Having done this, all of the helper methods defined in the OutputFileCodeTemplate and SqlCodeTemplate classes, such as GetDqlDbType(), IsUserDefinedType(), GetSqlParameterStatements(), and many more, are available to your template. Template inheritance thus provides a good way to reuse tested utility methods across multiple templates without cut-and-paste duplication of code.
Src
The Src attribute allows you to include functionality from another class in your template by dynamically compiling that class file as part of your template. Set the value of the attribute to point to the source file of the class that you want to include in the template. You use the Src attribute to enable the CodeSmith code-behind model.
Debug
The Debug attribute is used to determine whether or not debug symbols should be included in the generated assembly. Setting this attribute to True will enable you to set break points in your template using the System.Diagnostics.Debugger.Break( ) method.
LinePragmas
The LinePragmas attribute is used to determine whether or not line pragmas are generated during template compilation. When this attribute is set to True, template errors will point to the template source code. If it is set to False, then template errors will point to the compiled source code.
ResponseEncoding
The ResponseEncoding attribute is used to set the encoding for the template content and it's outputs. The ResponseEncoding attribute supports values from the System.Text.Encoding.GetEncoding method. By default, the encoding is set to ASCII.
OutputType
The OutputType attribute is used to set the output type of the template. The following values can be used:
- Normal - This is the default setting and will cause the output of the template to be written to the normal Response stream.
- Trace - This setting will cause the output of the template to be written to the Trace object.
- None - This setting will cause the template to not output anything. This is useful in a master template scenario where the template just calls other templates and outputs those to files and the master template itself doesn't output anything.
CompilerVersion
The CompilerVersion attribute is used to specify which compiler to use. For example, to use the .net 3.5 compiler, add the CompilerVersion attribute with a value of v3.5
Import Directive
The Import directive is used to import a namespace for use in your template. This lets you refer to types in other assemblies more conveniently. For instance, when you're using the SchemaExplorer assembly, you probably don't want to have to prefix every type from that assembly with the name of the assembly. The solution is to include an Import directive in your template along with the Assembly directive:
<%@ Assembly Name="SchemaExplorer" %> <%@ Import Namespace="SchemaExplorer" %>
There is one required attribute that you must supply to the Import directive.
Namespace
The Namespace attribute specifies the fully qualified name of the namespace to be imported.
Property Directive
To declare a property, you use a Property directive. For example, this directive defines a property named ClassName of type System.String:
<%@ Property Name="ClassName" Type="System.String" Category="Context" Description="The name of the class to be generated." %>
The Property directive has nine possible attributes. The Name and Type attributes are required, and the other attributes are optional.
Name
The Name attribute is used as the name of the property when it is displayed on the template's property sheet in CodeSmith Explorer. This is also the variable name that is used to store the value of the property within the template. This must be a legal variable name within the template's language. For example, if the template uses C# as its language, then the name must follow the rules for C# variables.
Type
The Type attribute specifies the .NET type of the property. This parameter can be any .NET data type, though for complex types you may need to specify an Editor attribute to allow the user to successfully supply a value for the property.
For scalar types, you must use Base Class Library types such as String or Int32 rather than language-specific types such as string or int.
Default
The Default attribute is used to set the default value for this property. If you omit this attribute, then CodeSmith does not supply a default value for the property.
Category
The Category attribute specifies what category this property should appear under in the CodeSmith Explorer property sheet. If you omit this attribute, CodeSmith will place the property in a category named Misc.
Description
The Description attribute supplies descriptive text to be displayed at the bottom of the property sheet when this property is selected.
Optional
The Optional attribute specifies whether or not this property is optional. If a user does not specify a parameter that is not optional then CodeSmith will not let them proceed. A value of true means that a value for the property is not required, and a value of false means that a value for the property is required.
Editor
The Editor attribute specifies the GUI editor that will be used in the property grid for this property. This is equivalent to placing an [EditorAttribute ] on a code property.
EditorBase
The EditorBase attribute specifies the base type for the editor. If none is specified, then UITypeEditor is assumed.
Serializer
The Serializer attribute specifies the IPropertySerializer type to use when serializing the property's values. This is equivalent to using a [PropertySerializerAttribute ].on a code property.
Register Directive
To register a sub-template, you include a Register directive in the master template. You can include as many Register directives as you like, so one master template can include multiple sub-templates. Sub-templates can be nested.
<%@ Register Template="Header.cst" MergeProperties="True" ExcludeProperties="IncludeMeta" %>
There are four attributes that you can supply to the Register directive. The Name and Template parameters are required; the others are optional.
Name
The Name attribute specifies the type name for the sub-template in the master template. It can be used to create an instance of the sub-template.
Template
The Template attribute specifies the relative path to the sub-template.
MergeProperties
The MergeProperties attribute specifies whether the properties of the sub-template should be dynamically added to the master template's properties. If you omit this attribute, it defaults to False.
ExcludeProperties
The ExcludeProperties attribute specifies a comma-delimited list of properties to be excluded from merging to the master template's property list. You may use * as a wildcard in the property list.
XmlProperty Directive
CodeSmith allows you to store metadata in external XML files. To incorporate XML metadata in your templates, you use an XmlProperty directive:
<%@ XmlProperty Name="PurchaseOrder" Schema="PO.xsd" Optional="False" Category="Data" Description="Purchase Order to generate packing list for." %>
The XmlProperty directive has six possible attributes. The Name attribute is required, and the other attributes are optional.
Name
The Name attribute is used as the name of the property when it is displayed on the template's property sheet in CodeSmith Explorer. This is also the variable name that is used to store the value of the property within the template. This must be a legal variable name within the template's language. For example, if the template uses C# as its language, then the name must follow the rules for C# variables. If a schema is specified, the variable will point to a strongly typed object model that CodeSmith generates based on the schema. If no schema is specified, it will point to an instance of the XmlDocument object.
Schema
The Schema attribute specifies an XSD schema to be used to parse the XML file chosen by the user at runtime.
Specifying a schema file allows CodeSmith to supply IntelliSense help for the XmlProperty instance within your template.
If you do not specify a value for the Schema attribute, then the user can select any XML document at runtime, and the property will return an instance of the XmlDocument class.
Default
The Default attribute is used to set the default value for this property. If you omit this attribute, then CodeSmith does not supply a default value for the property.
Category
The Category attribute specifies what category this property should appear under in the CodeSmith Explorer property sheet. If you omit this attribute, CodeSmith will place the property in a category named Misc.
Description
The Description attribute supplies descriptive text to be displayed at the bottom of the property sheet when this property is selected.
Optional
The Optional attribute specifies whether or not this property is optional. If a user does not specify a parameter that is not optional then CodeSmith will not let them proceed. A value of true means that a value for the property is not required, and a value of false means that a value for the property is required.
XmlProperty does not support all variations and features of XSD schemas. In general, if an XSD schema can be successfully loaded into the Visual Studio .NET schema designer then it should work in CodeSmith.