Mono.TextTemplating 2.3.1

There is a newer prerelease version of this package available.
See the version list below for details.
dotnet add package Mono.TextTemplating --version 2.3.1
NuGet\Install-Package Mono.TextTemplating -Version 2.3.1
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="Mono.TextTemplating" Version="2.3.1" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Mono.TextTemplating --version 2.3.1
#r "nuget: Mono.TextTemplating, 2.3.1"
#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 Mono.TextTemplating as a Cake Addin
#addin nuget:?package=Mono.TextTemplating&version=2.3.1

// Install Mono.TextTemplating as a Cake Tool
#tool nuget:?package=Mono.TextTemplating&version=2.3.1

Mono.TextTemplating

NOTE: To use a template at runtime in your app, you do not need to host the engine. It is generally preferable to use dotnet-t4 to generate a runtime template class and compile that into your app, as this has substantially less overhead than hosting the engine.

Mono.TextTemplating is an open-source reimplementation of the Visual Studio T4 text templating engine, and supports C# 10 and .NET 6. This package is the engine package, which can be used to host the T4 engine in your own app.

By default the engine uses the C# compiler from the .NET SDK, but the Mono.TextTemplating.Roslyn package can be used to bundle a copy of the Roslyn C# compiler and host it in-process. This may improve template compilation performance when compiling multiple templates, and guarantees a specific version of the compiler.

Usage

This will read a template from templateFile, compile and process it, and write the output to outputFile:

var generator = new TemplateGenerator ();
bool success = await generator.ProcessTemplateAsync (templateFilename, outputFilename);

This does the same thing as a series of lower-level steps, allowing it to provide additional compiler arguments by modifying the TemplateSettings:

string templateContent = File.ReadAllText (templateFilename);

var generator = new TemplateGenerator ();
ParsedTemplate parsed = generator.ParseTemplate (templateFilename, templateContent);
TemplateSettings settings = TemplatingEngine.GetSettings (generator, parsed);

settings.CompilerOptions = "-nullable:enable";

(string generatedFilename, string generatedContent) = await generator.ProcessTemplateAsync (
    parsed, inputFilename, inputContent, outputFilename, settings
);

File.WriteAllText (generatedFilename, generatedContent);

API Overview

Hosting

In most cases, you need only use or subclass TemplateGenerator:

  • It implements ITextTemplatingEngineHost and ITextTemplatingSessionHost with a default implementation that can be overridden if needed.
  • It wraps a TemplateEngine instance and provides simplified ProcessTemplateAsync() and PreprocessTemplateAsync() methods.

VS T4 Compatibility

Mono.TextTemplating has session, host and directive processor interfaces and classes in the Microsoft.VisualStudio.TextTemplating namespace that are near-identical to the original Visual Studio T4 implementation. This allows older T4 templates and directive processors to work with Mono.TextTemplating with few (if any) changes.

The Microsoft.VisualStudio.TextTemplating.(ITextTemplatingEngine,Engine) hosting API is supported but deprecated.

Advanced

For advanced use, some lower level classes and methods are accessible:

  • TemplatingEngine: generates C# classes from T4 templates and compiles them into assemblies
  • TemplateGenerator.ParseTemplate(): uses a Tokenizer to parse a template string into a ParsedTemplate
  • Tokenizer: tokenizes an T4 input stream
  • ParsedTemplate: provides direct access to the segments and directives of a parsed template
  • TemplatingEngine.GetSettings(): uses the directives in a ParsedTemplate to initialize a TemplateSettings
  • TemplateSettings: settings that control code generation and compilation.
  • CompiledTemplate: a template that has been compiled but not executed

Differences from VS T4

The Mono.TextTemplating engine contains many improvements over the original Visual Studio T4 implementation, including:

  • It supports the latest .NET APIs and C# language version
  • The engine and the code it generates are compatible with .NET Core and .NET 5+
  • It executes templates in an AssemblyLoadContext, which allows the generated assemblies to be garbage collected (where supported)
  • Parameter directives may use primitive types: <#@ parameter name="Foo" type="int" #>
Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 is compatible.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 is compatible. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 is compatible.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (15)

Showing the top 5 NuGet packages that depend on Mono.TextTemplating:

Package Downloads
Microsoft.EntityFrameworkCore.Design The ID prefix of this package has been reserved for one of the owners of this package by NuGet.org.

Shared design-time components for Entity Framework Core tools.

Microsoft.DotNet.Scaffolding.Shared The ID prefix of this package has been reserved for one of the owners of this package by NuGet.org.

Contains interfaces for Project Model and messaging for scaffolding.

dotnet-t4-project-tool

Project tool for processing T4 templates, a general-purpose way to generate text or code files using C#

PGCG.commonItems

Package Description

Mono.TextTemplating.Roslyn

In-process Roslyn compiler for the Mono.TextTemplating T4 templating engine

GitHub repositories (4)

Showing the top 4 popular GitHub repositories that depend on Mono.TextTemplating:

Repository Stars
dotnet/efcore
EF Core is a modern object-database mapper for .NET. It supports LINQ queries, change tracking, updates, and schema migrations.
linq2db/linq2db
Linq to database provider.
mono/monodevelop
MonoDevelop is a cross platform .NET IDE
dotnet/Scaffolding
Code generators to speed up development.
Version Downloads Last updated
3.0.0-preview-0052-g5d0f76c785 2,778 2/28/2024
3.0.0-preview-0049-g4f33c8d8b1 603 1/27/2024
3.0.0-preview-0045-g9b6fc72764 44,238 1/23/2024
3.0.0-preview-0027-g2711105671 2,495 10/3/2023
2.3.1 2,011,645 10/28/2022
2.3.0 6,533 10/5/2022
2.2.1 59,894,617 2/23/2021
2.2.0 30,469 12/5/2020
2.0.5 143,661 6/13/2019
2.0.4 8,354 4/4/2019
2.0.3 3,112 3/7/2019
2.0.2 4,004 12/14/2018
2.0.1 1,423 12/14/2018
2.0.0 1,347 12/13/2018
1.3.1 257,342 3/31/2017
1.3.0 48,588 3/17/2017
1.2.0 1,638 3/17/2017
1.1.0 9,118 3/14/2016
1.0.0 29,323 6/15/2014