Code Generation and T4 Text Templates

Applies to: yesVisual Studio noVisual Studio for Mac

Note

This article applies to Visual Studio 2017. 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

In Visual Studio, a T4 text template is a mixture of text blocks and control logic that can generate a text file. The control logic is written as fragments of program code in Visual C# or Visual Basic. In Visual Studio 2015 Update 2 and later, you can use C# version 6.0 features in T4 templates directives. The generated file can be text, such as a web page, or a resource file, or program source code in any language.

For a domain-specific language(DSL), designed to express statements in a particular problem space, learn how to Generate Code from a Domain-Specific Language

There are two kinds of T4 text templates: run time and design time

Run time T4 text templates

Run time templates are also known as 'preprocessed' templates. You run the templates in your application to produce text strings, as part of its output. For example, you can create a template to define an HTML page:

<html><body>
 The date and time now is: <#= DateTime.Now #>
</body></html>

Notice that the template resembles the generated output. The similarity of the template to the resulting output helps you avoid mistakes when you want to change it.

In addition, the template contains fragments of program code. You can use these fragments to repeat sections of text, to make conditional sections, and to show data from your application.

To generate the output, your application calls a function that is generated by the template. For example:

string webResponseText = new MyTemplate().TransformText();

Your application can run on a computer that doesn't have Visual Studio installed.

To create a run-time template, add a Preprocessed text template file to your project. You can also add a plain text file and set its Custom Tool property to TextTemplatingFilePreprocessor.

For more information, see Run-Time Text Generation with T4 Text Templates. For more information about the syntax of templates, see Writing a T4 Text Template.

Design time T4 text templates

Design time templates define part of the source code and other resources of your application. Typically, you use several templates that read the data in a single input file or database, and generate some of your .cs, .vb, or other source files. Each template generates one file and are built within Visual Studio or MSBuild.

For example, your input data could be an XML file of configuration data. Whenever you edit the XML file during development, the text templates regenerate part of the application code. One of the templates might resemble the following example:

<#@ output extension=".cs" #>
<#@ assembly name="System.Xml" #>
<#
 System.Xml.XmlDocument configurationData = ...; // Read a data file here.
#>
namespace Fabrikam.<#= configurationData.SelectSingleNode("jobName").Value #>
{
  ... // More code here.
}

The generated .cs file is in the following format based on the XML file values:

namespace Fabrikam.FirstJob
{
  ... // More code here.
}

As another example, the input could be a diagram of workflow in a business activity. When the users change their business workflow, or when you start work with new users who have a different workflow, it's easy to regenerate the code to fit the new model.

Note

The term model is sometimes used to describe data read by one or more templates. The model can be in any format, in any kind of file or database. It does not have to be a UML model or a Domain-Specific Language model. 'Model' just indicates that the data can be defined in terms of the business concepts, rather than resembling the code. Design-time templates are quicker and more reliable when changing the configuration as the requirements change. Typically, input is defined in terms of business requirements, as in the workflow example. Design-time templates are useful tools in an agile development process.

To create a design-time template, add a Text Template file to your project. Alternatively, you can add a plain text file and set its Custom Tool property to TextTemplatingFileGenerator.

For more information, see Design-Time Code Generation by using T4 Text Templates. For more information about the syntax of templates, see Writing a T4 Text Template.

The text template transformation feature is named T4.

See also