T4.BuildTools 3.0.0-preview-0049-g4f33c8d8b1

This is a prerelease version of T4.BuildTools.
There is a newer version of this package available.
See the version list below for details.
dotnet add package T4.BuildTools --version 3.0.0-preview-0049-g4f33c8d8b1                
NuGet\Install-Package T4.BuildTools -Version 3.0.0-preview-0049-g4f33c8d8b1                
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="T4.BuildTools" Version="3.0.0-preview-0049-g4f33c8d8b1" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add T4.BuildTools --version 3.0.0-preview-0049-g4f33c8d8b1                
#r "nuget: T4.BuildTools, 3.0.0-preview-0049-g4f33c8d8b1"                
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install T4.BuildTools as a Cake Addin
#addin nuget:?package=T4.BuildTools&version=3.0.0-preview-0049-g4f33c8d8b1&prerelease

// Install T4.BuildTools as a Cake Tool
#tool nuget:?package=T4.BuildTools&version=3.0.0-preview-0049-g4f33c8d8b1&prerelease                

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

Property Description
TransformOnBuild Set this to True to automatically transform T4Transform items on build. T4Preprocess items are transformed on build regardless of this setting unless legacy preprocessing is enabled.
T4DefaultNamespace Sets the namespace to be used when generating T4 classes. Defaults to the project's $(RootNamespace).
TransformOutOfDateOnly Setting this to False will disable the incremental build and force all template to be re-transformed.

Items

Item Description
T4Argument Pass a parameter value to the T4 templates, optionally scoped to a directive processor and/or directive. This may use Value metadata, with optional Processor and/or Directive metadata, or it may encode the value and processor into the Include with the <name=>=<value> or <processor>!<directive>!<name>!<value> formats used by the CLI t4 -a option.
DirectiveProcessor Register a custom directive processor by name. The Class and Assembly may be provided as metadata, or encoded into the Include with the <name>!<class>!<assembly> format used by the CLI t4 --dp option.
T4ReferencePath Adds a search directory for resolving assembly references in T4Transform templates. Affects <#@assembly#> directives and calls to the host's ResolveAssemblyReference(...) method.
T4IncludePath Adds a search directory for resolving <#@include#> directives in T4Transform and T4Preprocess templates. For T4Transform items, this also affects calls to the host's LoadIncludeText(...) method.
T4AssemblyReference Additional assemblies to be referenced when processing T4Transform items. May be a absolute path, or relative to the project or the T4ReferencePath directories.

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.

Metadata Description
OutputDirectory Set an output directory for the file generated by the template. If this is not set, it defaults to the directory containing the template file. It is evaluated relative to the project directory, not relative to the template file. If the directory does not exist, it wil; be created.
OutputFileName Set a filename to be used for the template output instead of deriving one from the template filename. If this is set, it will be the exact name used for the generated file. Any <#@extension..#> directive present in the template file will be ignored, and no other extension will be added. This filename may include directory components, and is evaluated relative to the template directory, which defaults to the directory containing the template file.

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:

Property Description
TransformFile Semicolon-separated list of template filenames. If TransformFile is set when invoking the TextTransform target explicitly, then only the templates specified by it will be transformed.
T4Arguments Semicolon-separated list of T4Argument items.

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.

Kind Name Description
Item T4ParameterValues Equivalent to T4Argument item
Property UseLegacyT4Preprocessing Place preprocessed templates beside the template files instead of dynamically injecting them into the build
Property IncludeFolders Equivalent to T4IncludePath items
Property PreprocessTemplateDefaultNamespace Equivalent to T4DefaultNamespace property
Property AfterTransform List of targets to run before template transformation. Use BeforeTargets="TransformTemplatesCore" instead.
Property AfterTransform List of targets to run after template transformation. Use AfterTargets="TransformTemplatesCore" instead.
Metadata DirectiveProcessor.Codebase Equivalent to Assembly metadata
Metadata T4Transform.OutputFilePath Equivalent to OutputDirectory metadata
There are no supported framework assets in this package.

Learn more about Target Frameworks and .NET Standard.

  • .NETFramework 4.8

    • No dependencies.
  • net6.0

    • No dependencies.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories (1)

Showing the top 1 popular GitHub repositories that depend on T4.BuildTools:

Repository Stars
xunit/xunit
xUnit.net is a free, open source, community-focused unit testing tool for .NET.
Version Downloads Last updated
3.0.0 566 9/3/2024
3.0.0-preview-0052-g5d0f76c785 7,186 2/28/2024
3.0.0-preview-0049-g4f33c8d8b1 164 1/27/2024
3.0.0-preview-0045-g9b6fc72764 107 1/23/2024
3.0.0-preview-0027-g2711105671 140 10/3/2023