Directive Syntax (Domain-Specific Languages)

Directive Syntax

Switch on low bandwidth view

Collapse All

Language Filter

This page is specific to

Microsoft Visual Studio 2008/.NET Framework 3.5

Other versions are also available for the following:

Domain-Specific Language Tools

Directive Syntax (Domain-Specific Languages)

Updated: July 2008

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

The five built-in directives are as follows:

Assembly
Import
Template
Output
Include

You can use generated directives to access models from text templates. Also, you can 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"]#>

Note:
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\"" #>

Note:

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\"" #>

Assembly

The assembly directive identifies an assembly to be referenced. This enables you to 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" #>

Note:
The file name can include the relative path.

Import

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" #>

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

Template

By using the template directive, you can specify characteristics of the generated transformation class. For example, you can specify 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
language	C#	C# VB	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"#>
inherits	TextTransformation	Any class that derives from TextTransformation.	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"#>
culture	"", 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.	Specifies the culture to use when an expression block is converted to text. For more information, see CultureInfo.
debug	true	true false	Specifies whether debugging is enabled. The following example shows how to enable debugging: <#@ template debug="true" #> For more information, see Troubleshooting Text Templates.
hostspecific	false	true false	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.

Output

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
Extension	.cs	Any string that satisfies the file system's rules for a file name extension.	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" #>
Encoding	"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.	Specifies what encoding should be used when the generated text output file is created. <#@ output encoding="ASCII"#> <#@ output encoding="UNICODE"#> <#@ output encoding="UTF-8"#>

Parameter Name

Default

Acceptable Values

Parameter Value

Extension

.cs

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

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" #>

Encoding

"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.

Specifies what encoding should be used when the generated text output file is created.

<#@ output encoding="ASCII"#>

<#@ output encoding="UNICODE"#>

<#@ output encoding="UTF-8"#>

Include

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" #>

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

Debugging

To debug text templates, you must set the debug parameter of the template directive. For more information, see Walkthrough: Debugging a Text Template.

Security

For more information, see Security of Text Templates.

Change History

Date	History	Reason
July 2008	Rewrote and refactored project.	Content bug fix.

Date

History

Reason

July 2008

Rewrote and refactored project.

Content bug fix.

Tasks

Concepts

Other Resources