The Text Template Transformation Process
Note
This article applies to Visual Studio 2015. If you're looking for the latest Visual Studio documentation, see Visual Studio documentation. We recommend upgrading to the latest version of Visual Studio. Download it here
The text template transformation process takes a text template file as the input and generates a new text file as the output. For example, you can use text templates to generate Visual Basic or C# code, or you can generate an HTML report.
Three components take part in this process: the engine, the host, and the directive processors. The engine controls the process; it interacts with the host and the directive processor to produce the output file. The host provides any interaction with the environment, such as locating files and assemblies. The directive processor adds functionality, such as reading data from an XML file or a database.
The text template transformation process is performed in two steps. First, the engine creates a temporary class, which is known as the generated transformation class. This class contains the code that is generated by the directives and control blocks. After that, the engine compiles and executes the generated transformation class to produce the output file.
Components
| Component | Description | Customizable (Yes/No) |
|---|---|---|
| Engine | The engine component controls the text template transformation process | No. |
| Host | The host is the interface between the engine and the user environment. Visual Studio is a host of the text transformation process. | Yes. You can write a custom host. |
| Directive Processors | Directive processors are classes that handle directives in text templates. You can use directives to provide data to a text template from an input source. | Yes. You can write custom directive processors |
The Engine
The engine receives the template as a string from the host, which handles all the files that are used in the transformation process. The engine then asks the host to locate any custom directive processors and other aspects of the environment. The engine then compiles and runs the generated transformation class. The engine returns the generated text to the host, which normally saves the text to a file.
The Host
The host is responsible for anything that relates to the environment outside the transformation process, including the following:
Locating text and binary files requested by the engine or a directive processor. The host can search directories and the global assembly cache to locate assemblies. The host can locate custom directive processor code for the engine. The host can also locate and read text files and return their contents as strings.
Providing lists of standard assemblies and namespaces that are used by the engine to create the generated transformation class.
Providing the application domain that is used when the engine compiles and executes the generated transformation class. A separate application domain is used in order to protect the host application from errors in the template code.
Writing the generated output file.
Setting the default extension for the generated output file.
Handling text template transformation errors. For example, the host can display the errors in the user interface or write them to a file. (In Visual Studio, errors are displayed in the Error Message Window.)
Providing a required parameter value if a user has called a directive without providing a value. The directive processor can specify the name of the directive and the parameter and ask the host to provide a default value if it has one.
Directives and Directive Processors
A directive is a command in your text template. It provides parameters to the generation process. Typically directives define the source and type of the model or other input, and the file name extension of the output file.
A directive processor can process one or more directives. When you transform a template, you must have installed a directive processor that can deal with the directives in your template.
Directives work by adding code in the generated transformation class. You call directives from a text template, and the engine processes all the directive calls when it creates the generated transformation class. After you call a directive successfully, the rest of the code that you write in your text template can rely on the functionality that the directive provides. For example, you can make the following call to the import directive in your template:
<#@ import namespace="System.Text" #>
The standard directive processor converts this to a using statement in the generated transformation class. You can then use the StringBuilder class in the rest of your template code without qualifying it as System.Text.StringBuilder.