Was this page helpful?
Your feedback about this content is important. Let us know what you think.
Additional feedback?
1500 characters remaining
Export (0) Print
Expand All
Important This document may not represent best practices for current development, links to downloads and other resources may no longer be valid. Current recommended version can be found here.

Directive Syntax (Domain-Specific Languages) 

Directives provide instructions to the text template transformation engine. These instructions depend on which type of directive you use: built-in, custom, or generated.

The five built-in directives are as follows:

You use generated directives to access models from text templates, and you use custom directives to access external data or to add custom functionality to text templates. For more information, see Architecture of Text Templates.

The generic syntax of a directive is:

<#@ DirectiveName [ParameterName = "ParameterValue"]#>

As shown, you must enclose each parameter value with opening and closing quotation marks. If the parameter value itself contains quotation marks, you must type the escape (\) character directly before each quotation mark character that is part of the parameter value. For example:

<#@ directivename parameter="\"quote\"" #>


The assembly directive identifies an assembly to be referenced so that you can use types within that assembly from code in the text template. Using the assembly directive is equivalent to using the Add Reference feature in Visual Studio.

In the following example, the directive name is assembly, the parameter name is name, and the parameter value is SomeLibrary.DLL:

<@ assembly name="SomeLibrary.DLL" #>

The file name can include the relative path.


By using the import directive, you can refer to types in a text template without providing a fully qualified name.

In the following example, the directive name is import, the parameter name is namespace, and the parameter value is System.Diagnostics:

<#@ import namespace="System.Diagnostics" #>

The value of the namespace parameter must be a valid .NET namespace identifier.


By using the template directive, you can specify characteristics of the generated transformation class, such as code language, class inheritance, culture, and the ability to debug. The template directive takes the following parameters, each of which is optional:

Parameter Name Default Acceptable Values Details





This parameter specifies which language, either Visual Basic or C#, has been used for code that is inside statement and expression blocks. All code that the engine generates in the transformation class must be expressed by using this language. The following example shows how to specify the Visual Basic language:

<#@ template language="VB"#>



Any class that derives from TextTransformation.

This parameter specifies which class should be used as the base class for the generated transformation class. The following example shows how to specify that the SomeClass class should be used:

<#@ template inherits="SomeClass"#>


"", the invariant culture.

A culture expressed as a string in the form xx-XX. For example, en-US, ja-JP, de-CH, de-DE, and others.

This parameter specifies the culture to use when an expression block is converted to text. For more information, see CultureInfo.





This parameter specifies whether debugging is enabled. The following example shows how to enable debugging:

<#@ template debug="true" #>

For more information, see How to: Debug Text Templates.





This parameter is used only with custom hosts. If you set the value of this parameter to true, you can access a property called Host in your text template. The property is a reference to the object that hosts the engine. You should set hostspecific to true only if you want to write a text template that is specific to a custom host and the text template calls the host at execution time. When hostspecific is true and you are using Visual Studio, you can call GetService to update your text templates.

For more information, see Creating Custom Text Template Hosts.


By using the output directive, you can specify characteristics of the generated text output, such as the file name extension. The output directive takes the following parameters, each of which is optional:

Parameter Name Default Acceptable Values Parameter Value



Any string that satisfies the file system's rules for a file name extension.

This parameter specifies the extension of the generated text output file. For example, you can specify a .cs or .vb extension if the generated text output is a code file. It is important to remember that the file name extension indicates only that the file is intended to be a particular format. The writer of the text template must make sure that the generated text meets the requirements of the intended format.

<#@ output extension=".txt" #>

<#@ output extension=".htm" #>

<#@ output extension=".cs" #>

<#@ output extension=".vb" #>


"Default", the current ANSI code page of the system.

Any of the following members of the Encoding

class expressed as a string: Default, ASCII, BigEndianUnicode, Unicode, UTF32, UTF7, UTF8.

This parameter specifies what encoding should be used when the generated text output file is created.

<#@ output encoding="ASCII"#>

<#@ output encoding="UNICODE"#>

<#@ output encoding="UTF8"#>


The include directive processes text from the specified file as if that text were included verbatim in the template currently being processed. In the following example, the name of the directive is include, the parameter name is file, and the parameter value is C:\test.txt:

<#@ include file="c:\test.txt" #>


If an include folder is entered in the registry, you do not have to specify the path of the file. For more information, see How to: Include Files in Text Templates.


To debug text templates, you must set the debug parameter of the template directive. For more information, see How to: Debug Text Templates.


For more information, see Security of Text Templates.

See Also

Community Additions

© 2015 Microsoft