Oleg Sych

Text Template Transformation Toolkit (T4) is a template-based code generation engine. It is included with Visual Studio 2008 and available as a download for Visual Studio 2005 in DSL and GAT toolkits. You can use T4 templates to generate Visual Basic, C#, T-SQL, XML or any other text files.

Syntax

T4 templates have ASP.NET-like syntax and consist of processing directives, text blocks and code blocks.

<#@ template language=“C#” #>
Hello
<# Write(”World!”) #>

Processing directives provide template compilation and processing options. In the example above, <#@ template #> directive specifies that code blocks of this template are written in C#.

Text blocks are copied to the output “as is”. In the example above, Hello is a text block.

Code blocks contain Visual Basic or C# code that can manipulate text blocks or generate template output directly. In the example above, the code block calls Write method which writes “World!” to the output file. Code blocks can use any available .NET APIs. For example, a template can use SMO to generate CRUD stored procedures for a table in a SQL Server database.

How it works

T4 engine performs two steps to generate output from a template.

During the first step, T4 engine “compiles” the template: it parses the processing instructions, text and code blocks, generates a concrete TextTransformation class, and compiles it into a .NET assembly. During the second step, T4 engine runs the compiled TextTransformation class, captures the actual output and saves it to a file.

Tools

Here are the tools you will be using when working with T4 text templates.

Visual Studio Custom Tool

T4 engine is integrated as a custom tool into Visual Studio 2008. When you add a text file with .tt extension to your project, Visual Studio assigns TextTemplatingFileGenerator as a custom tool and automatically generates output file from the template. This is similar to how Visual Studio generates strongly-typed DataSets from .xsd files.

Command Line Utility

T4 also includes a command line utility, TransformText, which you can use to process templates outside of Visual Studio (similar to xsd.exe for strongly-typed DataSets).

Editor

Text editing and debugging support for T4 templates is currently rather limited. T4 Editor (a free download) from Clarius Consulting provides IntelliSense and syntax highlighting in Visual Studio text editor for .tt files.

Debugger

Debugging requires placing calls to Debugger.Break method in code blocks to set breakpoints. Check out this post by Gareth Jones for more details. Hopefully, future versions of Visual Studio will provide a better debugging experience for T4 templates.

Visual Studio Templates

Visual Studio currently doesn’t provide provide a specific item for T4 templates in the Add New Project Item dialog. Hilton Giesenow created a set T4 Template Items that you can use. You may also find this article about creating Visual Studio Templates for T4 files useful. This article includes a ready-to-use T4 project item template.

Details

Here are some articles that will help you understand how template transformation works by showing how specific blocks and processing directives are “compiled”. Examples in these articles include the original template text, compiled template code and output file it produces.

• Text Blocks
• Statement Blocks
• Expression Blocks
• Class Feature Blocks
• <#@ template #> directive
• <#@ output #> directive
• <#@ import #> directive
• <#@ assembly #> directive
• <#@ include #> directive
• <#@ property #> directive

The following articles cover advanced topics of code generation with T4.

• T4 Architecture
• T4 Template Design
• Test runner for T4 unit tests 

Videos

There is a growing number of videos about T4 published on MSDN.

• How Do I: Create and Use T4 Templates (by Hilton Giesenow)

Examples

You can find some T4 examples on MSDN. You will notice that it has very limited information about use of T4 outside of DSL and Guidance packages. Here are some examples of standalone templates you can start using without having to build your own Software Factory.

• How to create a simple T4 template
• How to use T4 to generate .config files
• How to use T4 to generate Decorator classes
• How to use T4 to generate CRUD stored procedures
• How to use T4 to generate strongly-typed navigation class in ASP.NET (by Kirill Chilingarashvili)
• How to use T4 to generate strongly-typed AzMan wrapper
• How to generate multiple outputs from single T4 template
• T4 template for generating ADO.NET Entity Framework Stored Procedures  (by David DeWinter)
• T4 script for generating ADO.NET Entity Framework Views (by ADO.NET team)
• T4 template for generating LINQ to SQL Data Context (by Damien Guard)
• T4 template for generating WiX source files (by New Age Solutions)

Alternatives

As a code generation tool, T4’s purpose is similar to that of CodeDom (Code Document Object Model). CodeDom provides an API you can use to generate code in any .NET language from the same program. CodeDom API is low-level, complex, and has a steep learning curve. It is typically used for code generation in frameworks that need to to support multiple .NET languages. For example, T4 engine itself uses CodeDom; you have to use CodeDom to extend T4 with custom directives. Compared to CodeDom, T4 is easier to learn and use. However, T4 templates are language-specific. In other words, if you want to generate the same code code in C# and Visual Basic, you will need to create 2 separate T4 templates. Unlike CodeDom, T4 can generate any text files (XML, HTML, etc) and not just .cs or .vb files. This makes T4 a better fit for code generation in application development then CodeDom.

T4 engine is similar to CodeSmith, which has been around a lot longer, provides an excellent set of ready-to-use templates, better template editing and debugging experience for a reasonable price. Unlike CodeSmith, which was was designed to be a template-based code generation tool, T4 engine was designed as a supporting tool for Software Factories. T4 does not offer any reusable templates out of the box and provides rather limited documentation focused on use of T4 templates in DSL and Guidance packages. However, with inclusion in Visual Studio 2008, I think we will see more and more teams adopting T4 engine as a free alternative to CodeSmith.

T4 engine is also similar to NVelocity, an open-source template transformation engine. NVelocity was ported from Java and intends to stay as close to Jakarta Velocity as possible. This makes its template syntax different from ASP.NET and I would think that more people will prefer T4. I don’t know if a significant number of NVelocity templates are available at this time.