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:
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"]#>
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. 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" #>
You can specify the name of the assembly in any of the following forms:
The name of an assembly in the GAC.
The strong name of an assembly in the GAC, including version information such as name="Fabrikam.MyProject.AnAssembly, Version=10.0.0.0"
The name of an assembly that is included in the list of References of the Visual Studio project that contains the text template.
Building and testing assemblies that you reference from a text template
You cannot rebuild an assembly that is referenced from a text template, for some time after it has been executed in Visual Studio. This is because the Visual Studio text template host keeps the referenced assemblies loaded after the template has been executed. This strategy improves performance when there are multiple templates.
However, it presents a difficulty if you are actively developing and frequently rebuilding an assembly that you reference from a text template. There are several workarounds:
Stop and restart the Visual Studio instance in which you ran the text template.
Execute the text template using TextTransform.exe, during development of the assembly. For more information, see TextTransform.
Execute the assembly in unit tests, without using a text template.
Reference a copy of the assembly instead of its build location. This might be a useful tactic in a server build.
The Visual Studio text template host caches the assemblies that are built from a text template, to reduce the need to recompile templates. You can switch off this behavior by adding the string CacheAssemblies="false" to the registry key HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\10.0\TextTemplating. On a 64-bit system, use HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\VisualStudio\10.0\TextTemplating. However, this does not switch off retention of the AppDomain and referenced assemblies.
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. 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:
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"#>
You can also use language="C#v3.5" to specify a language version later than v2.0, which is used by default.
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"#>
You must also provide an assembly directive to reference the assembly in which the base class SomeClass is defined.
"", 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.
Specifies whether debugging is enabled. The following example shows how to enable debugging:
<#@ template debug="true" #>
For more information, see Troubleshooting Text Templates.
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. When hostspecific is true, this.Host is declared as Microsoft.VisualStudio.TextTemplating.ITextTemplatingEngineHost. If you have defined a custom host, you can cast it to the custom host type.
For example, using the standard Visual Studio host, you can use Host.ResolvePath(filename) to obtain the absolute path of a file in the project. You can also cast this.Host to IServiceProvider to obtain access to objects such as EnvDTE.Dte.
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:
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" #>
"Default", the current ANSI code page of the system.
The WebName string or CodePage number of any of the following members of the Encoding
Specifies what encoding should be used when the generated text output file is created.
<#@ output encoding="us-ascii"#>
<#@ output encoding="utf-16"#>
<#@ output encoding="utf-8"#>
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 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.
To debug text templates, you must set the debug parameter of the template directive. For more information, see Walkthrough: Debugging a Text Template.