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, 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"]#>
Hinweis
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" #>
Hinweis
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" #>
Hinweis
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 |
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 How to: Debug 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="UTF8"#> |
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" #>
Hinweis
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 How to: Debug Text Templates.
Security
For more information, see Security of Text Templates.
See Also
Concepts
Generating Artifacts Using Text Templates
Walkthrough: Creating and Running Text Templates
Architecture of the Text Template Transformation Process