Command-line tool

Meziantou.Framework.Templating.Tool renders template files without writing code: use it in scripts and builds to generate source code or configuration files.

The command reference lists every option of the tool.

Install the tool

Install it as a global tool:

dotnet tool install --global Meziantou.Framework.Templating.Tool

Render a template

--input is the template file. The text is written to the standard output:

Meziantou.Framework.Templating.Tool --input template.txt

Add --output to write it to a file instead. The folder of the file is created if needed:

Meziantou.Framework.Templating.Tool --input template.txt --output generated/result.txt

The template uses the syntax of the library. --root-directory sets the folder that relative input paths are read from; by default, the current folder.

Generate a file next to the template

A template can name the extension of the file it generates. Here, the outputextension directive asks for a .g.cs file:

<%@ outputextension .g.cs %>
// <auto-generated />
namespace Sample;

public static class Weekdays
{
<% foreach (var day in Enum.GetValues<DayOfWeek>()) { %>
    public const string <%= day %> = "<%= day.ToString().ToLowerInvariant() %>";
<% } %>
}

Meziantou.Framework.Templating.Tool --input Weekdays.template

The tool writes Weekdays.g.cs in the folder of the template. Its name is the name of the template with the extension replaced:

// <auto-generated />
namespace Sample;

public static class Weekdays
{
    public const string Sunday = "sunday";
    public const string Monday = "monday";
    public const string Tuesday = "tuesday";
    public const string Wednesday = "wednesday";
    public const string Thursday = "thursday";
    public const string Friday = "friday";
    public const string Saturday = "saturday";
}

The lines that only hold a directive or a statement block leave no empty line; see Line breaks. --output takes precedence over the directive.

Pass arguments

The template receives values through arguments. --arg name=value passes a string; repeat it for each argument. --arguments-file reads the arguments from the properties of a JSON object:

{
  "Product": "Contoso",
  "Version": 2,
  "Features": [ "Search", "Export" ]
}

The template uses the arguments as variables:

<%@ outputextension .txt %>
<%= Product %> <%= Version %> (<%= Channel %>)
<% foreach (var feature in Features.EnumerateArray()) { %>
- <%= feature.GetString() %>
<% } %>

Meziantou.Framework.Templating.Tool --input Release.template --arguments-file Release.json --arg Channel=preview

The tool writes Release.txt:

Contoso 2 (preview)
- Search
- Export

The type of an argument comes from its JSON value:

--arg values come after the file: an --arg replaces the property of the same name, and the last --arg of a name wins. A name must be a valid C# identifier and not a C# keyword, because it becomes the name of a parameter. The JSON file can contain comments and trailing commas.

Every template of the run receives every argument, and ignores the ones it does not use.

Render several templates

Repeat --input, or pass a glob pattern, to render several templates in one run. This is faster than one run per template, and the templates are compiled in parallel:

Meziantou.Framework.Templating.Tool --input "templates/**/*.tt" --output-directory generated --output-extension .txt

The patterns use the syntax of MSBuild: * and ? match a part of a name, ** matches any number of folders, and both / and \ separate folders. A value that names an existing file is that file, even when it contains * or ?. A template matched by several values is rendered once.

Each template generates its own file, so the standard output cannot be used. The name of the file is the name of the template with the extension of its output directive, or --output-extension when it has none. A template without a directive and without --output-extension is an error. The file is written:

• in --output-directory, when you set it. A template matched by a glob pattern keeps its path relative to the part of the pattern before the first wildcard: with templates/**/*.tt, templates/emails/welcome.tt generates generated/emails/welcome.txt. A template passed by its path is written at the root of the folder.
• next to the template otherwise.

A glob pattern always follows these rules, even when it matches a single template. --output names the file of a single template, so it cannot be used with several templates.

Before it renders anything, the tool checks the inputs: a pattern that matches no file, a template whose output file is unknown, two templates that generate the same file, and a generated file that would replace its template are reported, and no file is written. A template that fails to compile or to run does not stop the others: the tool renders them and exits with code 1.

Use T4-style templates

The tool also reads templates written with the delimiters of T4, <# and #>, and the output directive of T4. It detects them when the file contains a complete <# … #> block and no <%:

<#@ output extension=".txt" #>
<# foreach (var name in new[] { "Ada", "Grace" }) { #>
Hello <#= name #>!
<# } #>

Rendering Greeting.tt writes Greeting.txt:

Hello Ada!
Hello Grace!

Only the delimiters and the extension of the output directive come from T4: the code blocks and the other directives follow the syntax of the library. The T4 import, assembly and template directives are ignored; use <#@ using Namespace #> and <#@ reference path #> instead. include adds a C# file, not a template.

Choose other delimiters

--start-code-block-delimiter and --end-code-block-delimiter set the delimiters:

Meziantou.Framework.Templating.Tool --input template.txt --start-code-block-delimiter "{{" --end-code-block-delimiter "}}"

Pass both, unless you choose one of the known pairs: --start-code-block-delimiter "<#" alone implies #>, and <% implies %>.

Options

Errors

The tool exits with code 0 when it succeeds, and 1 when it fails, with a message on the standard error:

• a missing input file, an empty delimiter, a single unknown delimiter, an unknown line ending or encoding;
• an invalid argument or arguments file, or a problem with the inputs of a run of several templates (see Render several templates);
• a compilation error of the template, reported with the path of the template, the line and the column of the error;
• an exception thrown by the code of the template, reported as path(line,column): error: message, at the position of the code that threw it.