T4 Tutorial: Troubleshooting Code Generation Errors

This post is a part of the series that introduces code generation with Text Templates (also known as T4 Templates) in Visual Studio using C# and Visual Basic; explains how to create reusable templates and combine them in complex code generators. In order to follow examples in this article, you need to have Visual Studio 2008 Standard Edition or higher, SQL Server 2005 or later, T4 Toolbox and T4 Editor installed on your computer.

Template Transformation Process

There are two distinct stages in the process of generating output from a template or template transformation.

Compilation and Runtime Errors

During the first stage, the code generation Engine parses the template, uses text blocks, code blocks and directives to create a special class called GeneratedTextTransformation and compiles it in a temporary .NET assembly. Compilation Errors that occur during this stage include errors detected by the code generation engine in the template syntax and errors detected by the compiler when compiling GeneratedTextTransformation.

During the second stage, the Engine creates an instance of the GeneratedTextTransformation class, calls its TransformText method and saves the string it returns to the output file. Runtime errors that occur during this stage are exceptions thrown by code in GeneratedTextTransformation when it is running.

Troubleshooting Compilation Errors

Use Visual Studio to open CrudStoredProcedures.tt created in the previous article of this series (you can download the source code using links at the end of this article). As you remember, it’s a code generation file that produces a DELETE stored procedure using table schema information retrieved from SQL server using SMO.

C# and Visual Basic

Compilation Error, Code

  • Save the template file or select Run Custom Tool item from context menu in Solution Explorer to trigger template transformation.

Compilation Error, Error List

Code generation Engine reports errors in the Error List of Visual Studio. Compilation errors, like this one, include information about file and line where it occurred. You can double-click the error in the Error List to quickly jump to the location where it occurred in the template source code.

  • Correct spelling of the assembly directive, save the template file and verify compilation error is removed from the list.

Troubleshooting Runtime Errors

  • Simulate a runtime error by assigning null or Nothing to the server variable. This should trigger a run-time exception in the call to Database constructor.

Runtime error, C# code

Visual Basic

Runtime error, Visual Basic code

  • Save the template file or select Run Custom Tool item from context menu in Solution Explorer to trigger template transformation.

Runtime Error, Error List

Runtime errors are reported as exception stack dumps. Note that Line number for this error doesn’t point to the actual location of this error. Although the File column shows correct file name in this case, it will not be correct for runtime errors that occur in a template file referenced using include directive.

In order to troubleshoot runtime errors, we need to compile the template file with debugging information.


Debug parameter, C#

Visual Basic

Debug parameter, Visual Basic

  • Save the template file or select Run Custom Tool item from context menu in Solution Explorer to trigger template transformation.

Runtime Error with debugging information

Note that exception stack dump now includes file name and line number (CrudStoredProcedures.tt:line 8)pointing to the exact location where the error occurred. This will help you to find and fix simpler runtime errors. In more difficult cases, when the cause of the error is not as obvious, you may need to debug the template while it is running, which is the topic of my next post.

Troubleshooting Obscure Compilation Errors

Compiling the template file with debug information can also help in troubleshooting of obscure template compilation errors.


Obscure compilation error, C# template

Visual Basic

Obscure compilation error, Visual Basic template

We could have introduced this error by accident, perhaps in the process of converting statement blocks into class feature blocks or vice versa.

  • Save the template file or select Run Custom Tool item from context menu in Solution Explorer to trigger template transformation.

Obscure C# compilation errors

Visual Basic

Obscure Visual Basic compilation errors

As you can see, the compilation errors may be very confusing if you are looking at the template code. Fortunately, when compiling a template with debug information, code generation Engine saves the source code of GeneratedTextTransformation to a temporary file. Looking at this source code can help us understand the cause of an obscure compilation error like this.

  • Open the most recently modified .cs file from %TEMP% directory on your computer. You can find the exact location of this directory by executing “set %TEMP%” in command prompt window.

Compiled template code, C#

Visual Basic

Compiled template code, Visual Basic

Although the compilation errors reported in this scenario may be confusing when looking at the source code of the original template, by looking at the code of the compiled template we can see that code from the last block was placed at the class level in GeneratedTextTransformation, which explains the errors.

  • Correct the problem by removing the offending + from the template source code and saving the file.


Visual Studio makes it relatively easy to troubleshoot compilation errors that occur during code generation. Although in most cases, the error information it displays brings you directly to the source of problem, on rare occasions, you may need to look at the generated transformation code to determine what caused it. You can also use exception stack trace information Visual Studio displays to troubleshoot simple runtime errors. However, in more difficult cases, you will need to debug the code generation files, which we will talk about in the next article.


Source code, C#
Source code, Visual Basic

Write a Comment

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

Reader Comments

I’m finding that to get rid of some errors I’m having to close all windows and restart VS2008. Is this normal?
I’m starting from scratch, I don’t want to download any external tools until I see the basics working.
Is there an equivilent of clean I can run to make the compilation start from scratch?
Good website b.t.w.

Thanks, Anthony. Try the “Transform All Templates” button in the toolbar of Solution Explorer.

[…] Troubleshooting code generation errors […]