Text Template Transformation Toolkit


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.

T4 Template Transformation Process

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.

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

Videos

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.

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.

Information and Links

Join the fray by commenting, tracking what others have to say, or linking to it from your blog.


Other Posts
How to create a simple T4 template
POT without Guidance

Write a Comment

Take a moment to comment and tell us what you think. Some basic HTML is allowed for formatting.

Reader Comments

Reorganized Details section.
Added links:
- New article - Code Generation with Visual Studio Templates
- Hilton Giesenow’s post - T4 Template Items”
- Hilton Giesenow’s video - How Do I: Create and User T4 Templates
- Gareth Jones’ post - Debugging T4 Text Templates

Added a link to new article - <#@ property #> directive.

Fixed broken link to article How to create a simple T4 template

Added a link to new article - T4 Template Design.

[…] Sych has a large number of very, very good blog posts about T4, Oleg is THE T4 blogger out […]

Added a link to new post - How to use T4 to generate ADO.NET Entity Framework Stored Procedures (by David DeWinter)

[…] An explanatory series […]

- Updated the T4 Template Transformation Process image
- Added a link to new article - T4 Architecture

[…] them by hand. Furthermore, Ryan Hauert and I were toying around with the idea of using T4 Templates to generate the SQL we needed. In all honesty, we didn’t even consider modifying the […]