Code Generation in a Build Process

Article
02/04/2013

You can invoke text transformation as part of the build process of a Visual Studio solution. You can use this to ensure that files generated from the templates are up to date before they are compiled. This allows you to avoid a situation in which the user forgot to click Transform All Templates before building the project or checking in code. Text transformation tasks can be performed both by Visual Studio or MSBuild, and on a build server.

Including Text Transform tasks in Project Files

Install Visualization and Modeling SDK

To enable build tasks on your development computer, install Visual Studio Visualization and Modeling SDK.

To enable build tasks on a build server, see Text Transformation on a Build Server.

Edit the Project File

To invoke text transformation, you have to edit the file that defines your project. These properties cannot be edited in the project properties editor. Therefore, you must close the project and edit it as a text file.

To edit the text of the project file

In Solution Explorer, right-click the project and then click Unload Project.
Right-click the project again and then click Edit project.

The text of the project file appears in the XML editor.

To reopen the project when you have finished editing

Close the XML editor.
In Solution Explorer, right-click the project and then click Reload Project.

Import the Text Transformation Targets

The text transformation build tasks are defined in a single file. You must import it after the standard C# or Visual Basic targets.

To import the text transformation targets

Search the file for a line similar to one of these lines:

<Import Project="$(MSBuildToolsPath)\Microsoft.CSharp.targets" />

- or -

<Import Project="$(MSBuildToolsPath)\Microsoft.VisualBasic.targets" />
After that line, insert the Text Templating import:

<Import Project="$(MSBuildExtensionsPath)\Microsoft\VisualStudio\TextTemplating\v10.0\Microsoft.TextTemplating.targets" />

Set Properties to Control How the Build is Performed

Insert the following text in the project file. See the following sections for other properties that can be inserted in this property group.

<PropertyGroup>
 <TransformOnBuild>true</TransformOnBuild>
 <!-- Other properties can be inserted here -->
</PropertyGroup>

TransformOnBuild causes all the templates in the project to be executed when you build the project.

Invoking Transformation

Transforming All Templates in a Project Build

If you include the following property in the project file, all the text templates in the project will be executed whenever the project is built, subject to the incremental build feature.

You can invoke transforms either by pressing F5 in Visual Studio, or by using MSBuild. For example:

msbuild myproject.csproj

If you omit TransformOnBuild or set it to false, templates will not be transformed as an automatic part of project build.

Adding reference paths

You can add to the set of paths in which the host looks for assemblies referenced in templates. For example:

<ItemGroup>
    <!-- Add VS\...\PublicAssemblies to the list of places
         to look for assemblies used by templates. -->
    <T4ReferencePath Include="$(VsIdePath)PublicAssemblies\" />
</ItemGroup>

Transforming specific templates

You can transform specified files by invoking the Transform task with the msbuild utility. This task does not depend on the TransformOnBuild property, and it does not compile the project files. You must import the text templating targets file as described in a previous section.

For example, to transform a specific file:

msbuild myproj.proj /t:Transform /p:TransformFile=MyTemplate.tt

You can also use wildcard characters in the TransformFile parameter. For example, this command transforms all .tt files under the GeneratedCode folder:

msbuild dsl.csproj /t:Transform /p:TransformFile="GeneratedCode\**\*.tt"

Incremental Build

By default, the build manager tries to avoid executing a template if its output file is up-to-date. To do this, it monitors the file system to see which files are read by the template code. On subsequent occasions, it compares the modification dates of those files with the date of the output file. It executes the template if any input file has been modified more recently than the output file. The template is also executed if there is no information about previous executions of this template.

The result is that the output file will be regenerated if it is older than any of the following files:

The text template file
Files that are specified in <#@include#> directives
Files that are read by the code in the template
Files that are included or read by a directive processor used in the template

If you want to make sure that all templates are executed in every build, insert this property:

<TransformOutOfDateOnly>false</TransformOutOfDateOnly>

Source Control

There is no specific built-in integration with a source control system. However, you can add your own extensions, for example to check out and check in a generated file.

By default, the text transform task avoids overwriting a file that is marked as read- only, and when such a file is encountered, an error is logged in the Visual Studio error list, and the task fails.

To specify that read-only files should be overwritten, insert this property:

Unless you customize the postprocessing step, a warning will be logged in the error list when a file is overwritten.

Customizing the build process

You can customize the build process, for example to check out files that have been overwritten. Two customization points are provided, which are called before and after the transformation.

To define these points, define the properties $(BeforeTransform) and $(AfterTransform).

For example:

<PropertyGroup>
    <BeforeTransform>CustomPreTransform</BeforeTransform>
    <AfterTransform>CustomPostTransform;$(AfterTransform)</AfterTransform>
  </PropertyGroup>
  <Target Name="CustomPreTransform">
    <Message Text="In CustomPreTransform..." Importance="High" />
  </Target>
  <Target Name="CustomPostTransform">
    <Message Text="In CustomPostTransform..." Importance="High" />
  </Target>

In AfterTransform, you can reference the following lists:

GeneratedFiles - a list of files written by the process. For those files that overwrote existing read-only files, %(GeneratedFiles.ReadOnlyFileOverwritten) will be true. These files can be checked out of source control.
NonGeneratedFiles - a list of read-only files that were not overwritten.

Using these lists, you can, for example, check out overwritten files.

Text Transformation in a Build Server

If your build server runs on a computer on which Visual Studio is not installed, you should copy the following files to the build computer from a computer on which Visual Studio SDK is installed:

\Program Files\Microsoft Visual Studio 2010 SDK\VisualStudioIntegration\Common\Assemblies\v4.0\
- Microsoft.VisualStudio.TextTemplating.10.0.dll
- Microsoft.VisualStudio.TextTemplating.Interfaces.10.0.dll
- Microsoft.VisualStudio.TextTemplating.VSHost.10.0.dll
\Program Files\MSBuild\Microsoft\VisualStudio\TextTemplating\v10.0\
- Microsoft.VisualStudio.TextTemplating.Sdk.Host.10.0.dll
\Program Files\Microsoft Visual Studio 10.0\Common7\IDE\PublicAssemblies\
- Microsoft.VisualStudio.TextTemplating.Modeling.10.0.dll

For more information, see Create and Work with a Build Controller.