Upgrade your Internet Experience
Microsoft.com
Welcome Sign in
Visual Studio Extensibility
Click to Rate and Give Feedback
MSDN
MSDN Library
Visual Studio 2008
Visual Studio
Visual Studio SDK
 Directive Syntax
Collapse All/Expand All Collapse All
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:

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

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

 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.

 See Also

Tasks

Walkthrough: Creating and Running Text Templates

Concepts

Architecture of the Text Template Transformation Process
Accessing Models from Text Templates

Other Resources

Generating Artifacts By Using Text Templates
Using Built-in Directives in Text Templates
 Change History

Date

History

Reason

July 2008

Rewrote and refactored project.

Content bug fix.

Tags What's this?: Add a tag
Community Content   What is Community Content?
Add new content RSS  Annotations
VERSIONS IN ASSEMBLY DIRECTIVE      Andres Sommerhoff   |   Edit   |   Show History
(I belive the following might be useful for somebody)

You can declare the assembly version to use in T4 by declaring it inside the name string like the following example:

<#@ assembly name="Microsoft.SqlServer.Smo, Version=10.0.0.0" #>

I had to figure out this when I got the following error today:

error BC32206: Compiling transformation: The project currently contains references to more than one version of Microsoft.SqlServer.Smo, a direct reference to version 9.0.242.0 and an indirect reference (through 'CustomProyectDLL') to version 10.0.0.0. Change the direct reference to use version 10.0.0.0 (or higher) of Microsoft.SqlServer.Smo.

Inherits parameter in TEMPLATE directive (to use an external .dll)      Andres Sommerhoff   |   Edit   |   Show History

If you want to inherit from a class defined in an external .dll file, you have to include a link to it in the ASSEMBLY directive in addition to use the INHERITS parameter of the TEMPLATE directive. As example:

<#@ template inherits="CustomNamespace.CustomClass" #>
<#@ Assembly Name="path/CustomClass.dll" #>

... or if you install your dll in the GAC:

<#@ template inherits="CustomNamespace.CustomClass" #>
<#@ Assembly Name="CustomClass" #>

Otherwise your will get the following error:


"Failed to load base class '{0}' from which Transformation class inherits"

Assembly Directive &amp; Relative Path      Relative Name   |   Edit   |   Show History
Although the note bellow the assembly directive states "The file name can include the relative path. " it actually fails with the following error:

Error 1 The host threw an exception while trying to resolve the assembly reference '<relative path to the dll>'.
The transformation will not be run. The following Exception was thrown:
System.IO.FileLoadException: The given assembly name or codebase was invalid. (Exception from HRESULT: 0x80131047)
at System.Reflection.AssemblyName.nInit(Assembly& assembly, Boolean forIntrospection, Boolean raiseResolveEvent)
at System.Reflection.AssemblyName.nInit()
at System.Reflection.AssemblyName..ctor(String assemblyName)
at Microsoft.VisualStudio.TextTemplating.GlobalAssemblyCacheHelper.GetLocation(String strongName)
at Microsoft.VisualStudio.TextTemplating.VSHost.TextTemplatingService.ResolveAssemblyReference(String assemblyReference)
at Microsoft.VisualStudio.TextTemplating.Engine.CompileAndRunCode(String generatorCode, ITextTemplatingEngineHost host, TemplateProcessingSession session)
....................................................
Tags What's this?: Add a tag
Flag as ContentBug
© 2009 Microsoft Corporation. All rights reserved. Terms of Use | Trademarks | Privacy Statement
Page view tracker