The CodeTemplate Directive

Every CodeSmith Generator template must start with a CodeTemplate directive. Every template must contain precisely one CodeTemplate directive. The only thing that can appear before the CodeTemplate directive in the template is one or more comments.

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. For example, here's the CodeTemplate directive from the SortedList.cst sample template:

<%@ CodeTemplate Language="VB" 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 as its own code-behind language, and that it produces VB output. It also includes a description of the purpose of the template.

CodeTemplate Directive Attributes

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 Generator doesn't use it in any way to generate the template's output. The Template Editor 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.

Inherits

By default all CodeSmith Generator templates inherit from CodeSmith.Engine.CodeTemplate. 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 Generator must also be able to find this class. To ensure this, you must either 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 BaseTemplates sample project included with your CodeSmith Generator 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 Language="CS" 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 GetSqlDbType(), 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 Generator code-behind model.

Debug

The Debug attribute is used to determine whether or not debug symbols should be included in the generated assembly. Click here to learn more about debugging.

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.

NoWarn

Comma-delimited list of the warning ID numbers that the template compiler should suppress. These are standard C# / VB compiler warning ID numbers.

ClassName

The ClassName attribute is used to specify the class name of the compiled template. This attribute should be defined when using partial code-behinds.

Namespace

The Namespace attribute is used to specify the namespace for the compiled template. This attribute should be defined when using partial code-behinds.

Encoding

The Encoding attribute allows you to define the encoding the current template output and template document will be saved as. The default encoding of a template document is UTF-8.