Oleg Sych

This article is a part of a series that introduces code generation using C# and Text Templates (also known as T4 Templates) in Visual Studio; 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, T4 Toolbox and T4 Editor installed on your computer.

Overview

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

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.

Setup

Use Visual Studio to open CrudStoredProcedures.tt created in the previous article of this series. 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.

<#@ template language="C#" #>
<#@ output extension="sql" #>
<#@ assembly name="Microsoft.SqlServer.ConnectionInfo" #>
<#@ assembly name="Microsoft.SqlServer.Smo" #>
<#@ import namespace="Microsoft.SqlServer.Management.Smo" #>
<#
    Server server = new Server();
    Database database = new Database(server, "Northwind");
    Table table = new Table(database, "Products");
    table.Refresh();
#>
create procedure <#= table.Name #>_Delete
<#
    PushIndent("\t");
    foreach (Column column in table.Columns)
    {
        if (column.InPrimaryKey)
            WriteLine("@" + column.Name + " " + column.DataType.Name);
    }
    PopIndent();
#>
as
    delete from <#= table.Name #>
    where
<#
    PushIndent("\t\t");
    foreach (Column column in table.Columns)
    {
        if (column.InPrimaryKey)
            WriteLine(column.Name + " = @" + column.Name);
    }
    PopIndent();
#>    

Troubleshooting Compilation Errors

• Simulate a parsing error by misspelling one of the assembly directives as assembl. 

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

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 to the server variable. This should trigger a run-time exception in the call to Database constructor.

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

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.

• Set debug parameter of the template directive to "True".

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

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.

• Simulate a compilation error by adding an empty class feature block followed by a couple of trailing spaces on the last line of the template file.

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

As you can see, the three compilation errors simply don’t make sense 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.

As you can see, the couple of trailing white spaces we placed on the last line, was incorrectly interpreted as a text block and converted to a Write method call at the class level in GeneratedTextTransformation. This is a bug in the code generation Engine, but knowing what triggers it allows us to easily work around it.

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

Conclusion

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.