Processing Text Templates by using a Custom Host
This article applies to Visual Studio 2015. If you're looking for the latest Visual Studio documentation, use the version selector at the top left. We recommend upgrading to Visual Studio 2019. Download it here
The text template transformation process takes a text template file as the input and produces a text file as the output. You can call the text transformation engine from a Visual Studio extension, or from a standalone application running on a machine on which Visual Studio is installed. However, you must provide a text templating host. This class connects the template to the environment, finding resources such as assemblies and include files, and dealing with the output and error messages.
If you are writing a package or extension that will run within Visual Studio, consider using the text templating service, instead of writing your own host. For more information, see Invoking Text Transformation in a VS Extension.
We do not recommend using text template transformations in server applications. We do not recommend using text template transformations except in a single thread. This is because the text templating Engine re-uses a single AppDomain to translate, compile, and execute templates. The translated code is not designed to be thread-safe. The Engine is designed to process files serially, as they are in a Visual Studio project at design time.
For run-time applications, consider using preprocessed text templates: see Run-Time Text Generation with T4 Text Templates.
If your application uses a set of templates that are fixed at compile time, it is easier to use Preprocessed Text Templates. You can also use that approach if your application will run on a machine on which Visual Studio is not installed. For more information, see Run-Time Text Generation with T4 Text Templates.
Executing a Text Template in Your Application
To execute a text template, you call the ProcessTemplate method of Microsoft.VisualStudio.TextTemplating.Engine:
using Microsoft.VisualStudio.TextTemplating; ... Engine engine = new Engine(); string output = engine.ProcessTemplate(templateString, host);
Your application must find and provide the template, and must deal with the output.
host parameter, you must provide a class that implements ITextTemplatingEngineHost. This is called back by the Engine.
The host must be able to log errors, resolve references to assembly and include files, provide an Application Domain in which the template can execute, and call the appropriate processor for each directive.
Microsoft.VisualStudio.TextTemplating.Engine is defined in Microsoft.VisualStudio.TextTemplating.*.0.dll, and ITextTemplatingEngineHost is defined in Microsoft.VisualStudio.TextTemplating.Interfaces.*.0.dll.
In This Section
Walkthrough: Creating a Custom Text Template Host Shows you how to create a custom text template host that makes the text template functionality available outside Visual Studio.
The Text Template Transformation Process Describes how text transformation works, and which parts you can customize.
Creating Custom T4 Text Template Directive Processors Provides an overview of text template directive processors.