T4 Tutorial: Execute templates at build time

This is not so hard to do actually. It ensures your transformations are executed when you build your solution, when in some cases you did not click ‘Build > Transform all T4 Templates’ when changes are made to your .tt files.

If one of your projects uses T4 to generate code, and you want it to execute at build time, consider the next steps:

Unload your project

Righ-click on the project in your solution explorer and click ‘unload’.

Open the .csproj of your project

Right-click again and select ‘edit projectname.csproj’

Edit the .csproj file

Add following PropertyGroup at the beginning of your csproj file (for VS2017):

<PropertyGroup>
    <VisualStudioVersion Condition="'$(VisualStudioVersion)' == ''">15.0</VisualStudioVersion>
    <VSToolsPath Condition="'$(VSToolsPath)' == ''">$(MSBuildExtensionsPath32)\Microsoft\VisualStudio\v$(VisualStudioVersion)</VSToolsPath>
    <TransformOnBuild>true</TransformOnBuild>
   <OverwriteReadOnlyOutputFiles>true</OverwriteReadOnlyOutputFiles>
    <TransformOutOfDateOnly>false</TransformOutOfDateOnly>
</PropertyGroup>

The TransformOnBuild property set tot true ensures the templates to be transformed when you build your project (false by default).

OverwriteReadOnlyOutputFiles forces overwriting of readonly output files.

Set TransformOutOfDateOnly to false to transform files even if the output is up to date.

At the end of yoru csproj file, add following import:

<Import Project="$(VSToolsPath)\TextTemplating\Microsoft.TextTemplating.targets" />

Now you can reload your project and you are done. All T4 Templates within this project will be executed on each build.

T4 Beginner Tutorial: Generate C# classes based on text definitions

Introduction

T4 stands for Text Template Transformation Toolkit. When you scaffold a controller or view in ASP.NET, in the background T4 Templates that contain those structures are executed and files are generated for you.

In this article I will explain how you can generate classes yourself, based on simple definitions in a text file. This is a easy way to understand how T4 templating works and afterwards you should be able to create your own templates.
Here you can find more information about T4 templates.

Create your first template

In the solution explorer, right click on your project and choose ‘add > new item’ and pick the ‘Text Template’

Name it ‘Models.tt’ and add it to your project.

<#@ template debug="false" hostspecific="false" language="C#" #>
<#@ assembly name="System.Core" #>
<#@ import namespace="System.Linq" #>
<#@ import namespace="System.Text" #>
<#@ import namespace="System.Collections.Generic" #>
<#@ output extension=".txt" #>

In the template code above we can see that ‘<#@  #>’ tags are used to enclose the ‘directives’, by default the System.Linq, System.Text and System.Collections.Generic namespaces are imported. You can import any namespace like this. More information about template directives here.

Note that the ‘output extension’ is set to ‘.txt’. Since we are generating C# classes, we have to change this to ‘.cs’.

<#@ output extension=".cs" #>

To execute a template, choose ‘Build’ in the menu and select Transform all T4 templates’. You can also let Visual Studio transform your templates whenever you build your solution or project. See my other post here.

Control blocks

<# Statement blocks #>

With statement blocks we can embed C# code in our template, everything that is not inside these block is written to the generated file.

<#@ template debug="false" hostspecific="false" language="C#" #>
<#@ assembly name="System.Core" #>
<#@ import namespace="System.Linq" #>
<#@ import namespace="System.Text" #>
<#@ import namespace="System.Collections.Generic" #>
<#@ output extension=".cs" #>

// This is output
<#  
/* Code goes inside this statement block */
#>
// More output

In VS, if the T4 template is executed, the resultant .cs file is created as a child node off of the template’s node (in the solution explorer).

<#+ Class Feature Blocks #>

With class feature blocks you can write code that is reusable in your template. Here you can write code to use in your statement blocks.

<#= GenerateComment(“This is a comment”)  #>

<#+
public string GenerateComment(string comment)
{
 return $“/* {comment} */”;
}
#>

<#= Expression Blocks #>

With expression blocks you can pass data to the generated output.

<#
string[] namespaces = {"System" ,"System.Linq"};

for(int i = 0; i < namespaces.Length; i++)
{
#>
using <#= namespaces[i] #>;
<#
}
#>

More information about control blocks click here.

Define your classes

Time to generate some models. In this tutorial, I choose to read model and property definitions from a plain text file. By doing so, we can easily add more models to generate. Create a text file in the same folder named ModelDefinitions.txt‘ and add following text:

Product
Id : Guid
Name : string
Price : int

Order
Id : Guid
Products : List<Product>

Mind the indentations.

Inside our template we will have to locate the definitions so we can read them. Inside statements blocks we can write code to do this. To achieve this we must acces ‘this.Host’ to use the ‘ResolvePath’ method by setting ‘hostpecific’ to true. We must also import the ‘System.IO’ namespace.

At the bottom of our template we can also add a class feature block to create the models we need in order to generate our classes.

<#@ import namespace="System.IO" #>
<#@ template debug="false" hostspecific="true" language="C#" #>
<# 
string path = this.Host.ResolvePath(@"ModelDefinitions.txt");
var modelDefinitions = File.ReadLines(path).ToArray();
#>

<#+
public class ModelDefinition
{
	public string Name { get; set; }
	public PropertyDefinition[] Properties { get; set; }
}

public class PropertyDefinition
{
	public PropertyDefinition(string name, string type)
	{
		Name = name;
		Type = type;
	}

	public string Name { get; set; }
	public string Type { get; set; }
}

Create classes

We read the lines of the definition file and fill up a list of ModelDefinition objects. Let’s create a method that iterates over the lines and detects when a word starts at the beginning of a string. This way we can find what line is a model definition, and we can achieve this by using a regular expression.

Add the following code to the class feature block:

<#@ import namespace="System.Text.RegularExpressions" #>

public List<ModelDefinition> GenerateModels(string[] lines)
{
	List<ModelDefinition> result = new List<ModelDefinition>();
	var lineNumber = -1;

	foreach(var line in lines)
	{
		lineNumber++;
		if (String.IsNullOrEmpty(line)) continue;
		
		var match= Regex.Match(line, @"^[^\s].+");

		if(match.Success)
		{
			var model = new ModelDefinition
			{
				Name = line
			};

			result.Add(model);
		}
	}
	return result;
}

Generate code

Now we are can already generate empty Product and Order classes. Add following code to the template so it looks like this:

<#@ template hostspecific="true" language="C#" #>
<#@ output extension=".cs" #>
<#@ assembly name="System.Core" #>
<#@ import namespace="System.IO" #>
<#@ import namespace="System.Linq" #>
<#@ import namespace="System.Text" #>
<#@ import namespace="System.Text.RegularExpressions" #>
<#@ import namespace="System.Collections.Generic" #>
<#
string path = this.Host.ResolvePath(@"ModelDefinitions.txt");
var definitions= File.ReadLines(path).ToArray();
#>
//This code is auto-generated. Changes to this file will be lost! 
using System;

namespace Solution.Project.Models
{
<#
List<ModelDefinition> models = GenerateModels(definitions); 

foreach (var model in models)
{
#>
	public class <#= model.Name #>
	{
	}
<#
}
#>
}
<#+
// ….

Output in Models.cs:

//This code is auto-generated. Changes to this file will be lost! 
using System;

namespace Solution.Project.Models
{
	public class Product
	{
	}
	public class Order
	{
	}
}

We can also use a regular expression to find out what lines are property definitions and distinguish their names and types. Let’s add GenerateProperties method that will iterate over the lines, starting from the line number of the model definition. We know that all the next property definitions belong to this model, until we have a empty line.

Add the GenerateProperties method to the class feature block, and change the GenerateModels method as following:

public List<ModelDefinition> GenerateModels(string[] lines)
{
	List<ModelDefinition> result = new List<ModelDefinition>();
	var lineNumber = -1;

	foreach(var line in lines)
	{
		lineNumber++;
		if (String.IsNullOrEmpty(line)) continue;
		
		var match= Regex.Match(line, @"^[^\s].+");

		if(match.Success)
		{
			var model = new ModelDefinition
			{
				Name = line,
				Properties = GenerateProperties(lineNumber, lines)
			};

			result.Add(model);
		}
	}
	return result;
}

public PropertyDefinition[] GenerateProperties(int lineNumber, string[] lines)
{
	List<PropertyDefinition> properties = new List<PropertyDefinition>();

	for (var i = lineNumber + 1; i < lines.Length; i++)
	{
		var match = Regex.Match(lines[i], @"^\s+(?<name>[^:]+)(?<center>[\s]?:[\s]?)(?<type>[^\?\s\?]+)");

		if (match.Success)
		{
				properties.Add(new PropertyDefinition(match.Groups["name"].Value, match.Groups["type"].Value ));
		}
		else
		{
			break;
		}
	}
	return properties.ToArray();
}

That’s it! All that’s is left to do is adjust our template so that can add out properties to the output. Adjust the template as shown below:

<#@ template hostspecific="true" language="C#" #>
<#@ output extension=".cs" #>
<#@ assembly name="System.Core" #>
<#@ import namespace="System.IO" #>
<#@ import namespace="System.Linq" #>
<#@ import namespace="System.Text" #>
<#@ import namespace="System.Text.RegularExpressions" #>
<#@ import namespace="System.Collections.Generic" #>
<#
string path = this.Host.ResolvePath(@"..\Definitions\Models.txt");
var definitions= File.ReadLines(path).ToArray();
#>
//This code is auto-generated. Changes to this file will be lost! 
using System;

namespace TextTran.Transformations.Models
{
<#
List<ModelDefinition> models = GenerateModels(definitions); 
foreach (var model in models)
{
#>
	public class <#= model.Name #>
	{
<#
	foreach (var property in model.Properties)
	{
#>
		public <#= property.Type #> <#= property.Name #> { get; set; }

<# 
	}
#>
	}

<#
}
#>
}

If all goes well, the Models.cs file should now look like this:

//This code is auto-generated. Changes to this file will be lost! 
using System;
using System.Collections.Generic;

namespace TextTran.Transformations.Models
{
	public class Product
	{
		public Guid Id { get; set; }

		public string Name { get; set; }

		public int Price { get; set; }

	}

	public class Order
	{
		public Guid Id { get; set; }

		public List<Product> Products { get; set; }

	}
}

Just keep adding definitions, execute the template and voila, your classes are generated for you! You can use this template and adjust it to your needs if you like. There’s more to add to the template: nullable type support, comments and summaries. I have already done this on my experimental project found on my GitHub repository. Feel free to use my code to practice.

Appendix

We can tidy up the template by moving the class feature block and directives to a ‘TemplateManager.tt” file. By adding a include directive in our template we can use all imports and logic defined in the TemplateManager. Full example below:

TemplateManager.tt

<#@ template hostspecific="true" language="C#" #>
<#@ output extension=".cs" #>
<#@ assembly name="System.Core" #>
<#@ import namespace="System.IO" #>
<#@ import namespace="System.Linq" #>
<#@ import namespace="System.Text" #>
<#@ import namespace="System.Text.RegularExpressions" #>
<#@ import namespace="System.Collections.Generic" #>
<#+
public List<ModelDefinition> GenerateModels(string[] lines)
{
	List<ModelDefinition> result = new List<ModelDefinition>();
	var lineNumber = -1;

	foreach(var line in lines)
	{
		lineNumber++;
		if (String.IsNullOrEmpty(line)) continue;
		
		var match= Regex.Match(line, @"^[^\s].+");

		if(match.Success)
		{
			var model = new ModelDefinition
			{
				Name = line,
				Properties = GenerateProperties(lineNumber, lines)
			};

			result.Add(model);
		}
	}
	return result;
}

public PropertyDefinition[] GenerateProperties(int lineNumber, string[] lines)
{
	List<PropertyDefinition> properties = new List<PropertyDefinition>();

	for (var i = lineNumber + 1; i < lines.Length; i++)
	{
		var match = Regex.Match(lines[i], @"^\s+(?<name>[^:]+)(?<center>[\s]?:[\s]?)(?<type>[^\?\s\?]+)");

		if (match.Success)
		{
				properties.Add(new PropertyDefinition(match.Groups["name"].Value, match.Groups["type"].Value ));
		}
		else
		{
			break;
		}
	}
	return properties.ToArray();
}
#>

Models.tt

<#@ include file="TemplateManager.tt" #>
<#
string path = this.Host.ResolvePath(@"..\Definitions\Models.txt");
var definitions= File.ReadLines(path).ToArray();
#>
//This code is auto-generated. Changes to this file will be lost! 
using System;

namespace TextTran.Transformations.Models
{
<#
List<ModelDefinition> models = GenerateModels(definitions); 
foreach (var model in models)
{
#>
	public class <#= model.Name #>
	{
<#
	foreach (var property in model.Properties)
	{
#>
		public <#= property.Type #> <#= property.Name #> { get; set; }

<# 
	}
#>
	}

<#
}
#>
}

Have fun experimenting!