The CodeTemplate Directive

Owned by Autumn Wilkins (Unlicensed)
Last updated: Dec 12, 2011 by AnonymousVersion comment
4 min read

Every CodeSmith 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 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 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 .NET 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 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 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 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 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 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 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.
NoWarn

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

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

<%@ CodeTemplate Language="C#" TargetLanguage="Text" CompilerVersion="v3.5" Description="Sample using .net 3.5 syntax" %>