T4.BuildTools 3.0.0-preview-0049-g4f33c8d8b1

T4.BuildTools

T4.BuildTools is a set of MSBuild tasks and targets for for processing T4 templates, a general-purpose way to generate text or code files using C#.

It's part of Mono.TextTemplating, a modern open-source reimplementation of the Visual Studio T4 text templating engine.

Usage

These targets introduce two new MSBuild item types: T4Transform and T4Preprocess. They are processed automatically during the build and when saving the template file in Visual Studio.

NOTE: These items are processed using the Mono.TextTemplating T4 engine and host. Host-specific templates will not have access to the Visual Studio T4 host.

T4Transform items are transformed when saving the template in Visual Studio and when explicitly invoking the TransformTemplate MSBuild target. The TransformOnBuild property can be set to transform the templates on every build by calling this target automatically. The build is incremental by default, so a template will only be transformed if its input files are newer than its output.

T4Preprocess items are preprocessed into a class that can be instantiated and executed from project code. The preprocessed class is generated in the intermediate output directory and included in the build automatically, similar to a source generator.

Customizing the Build

Template transformation can be customized using a range of MSBuild properties, items and metadata.

Properties

Items

Both T4Argument and DirectiveProcessor items support either setting metadata via MSBuild metadata or encoding it into the Include in the same format supported by the options of the t4 CLI tool. If both encoded metadata and MSBuild metadata are present, the MSBuild metadata takes precedence.

NOTE: Encoded metadata is supported for convenience, and to support parsing T4Argument items from the T4Arguments property. However, using MSBuild metadata is preferred when possible as it allows simplified manipulation of the items.

For example, the following T4Argument items are equivalent:

<ItemGroup>
  <T4Argument Include="Greeting" Value="Hello" />
  <T4Argument Include="Greeting=Hello" />
</ItemGroup>

As are the following T4Argument items:

<ItemGroup>
  <T4Argument Include="Month" Value="June" Processor="MyProcessor" Directive="MyDirective" />
  <T4Argument Include="Month=June" Processor="MyProcessor" Directive="MyDirective" />
  <T4Argument Include="MyProcessor!MyDirective!Month!June" />
</ItemGroup>

Similarly, the following DirectiveProcessor items are equivalent:

<ItemGroup>
  <DirectiveProcessor Include="MyProcessor" Class="Me.MyProcessor" Assembly="MyProcessors.dll" />
  <DirectiveProcessor Include="MyProcessor!Me.MyProcessor!MyProcessors.dll" />
</ItemGroup>

Item Metadata

T4Transform items have optional metadata that can be used to control the path used for the generated output. These can also be used for T4Preprocess items when using legacy preprocessing.

CLI Properties

There also are several properties that are intended to be passed in when invoking the target on the CLI and should not be used in project/targets files:

For example:

dotnet msbuild -t:TransformTemplates -p:TransformFile=Foo.cs -p:T4Arguments="Foo=1;Bar=2"

Target Extensibility

The TransformTemplatesCore target is provided as an extension points for custom targets that require running before or after template processing. This target runs when automatic or explicit transformation takes place, whereas the TransformTemplates target only runs when invoked explicitly.

The outputs of the transformed and preprocessed templates are available as GeneratedTemplateOutput and PreprocessedTemplateOutput items respectively, and assemblies referenced by preprocessed templates are available as T4RequiredAssemblies items.

These items are only available after the transform targets have run, so are not available in the MSBuild project at evaluation time. To access them in custom targets, use AfterTargets="TransformTemplatesCore" to order your target after template transformation.

For example:

<Target Name="MyCustomTarget" AfterTargets="TransformTemplatesCore">
  <Message Text="Transformed templates: @(GeneratedTemplates)" />
  <Message Text="Preprocessed templates: @(PreprocessedTemplates)" />
  <Message Text="Preprocessed assemblies: @(T4RequiredAssemblies)" />
</Target>

Legacy Compatibility

The following properties, items and metadata are provided for partial backwards compatibility with the Visual Studio Microsoft.TextTemplating MSBuild targets.