If you already have installed T4 Toolbox previously, please make sure you have version 8.11.12.1 or later.

Introduction

Error conditions exist in code generators just like in all other kinds of software. And just like with any other type of software, it is important to handle error conditions appropriately. One one hand, a code generator should handle the expected error conditions and display information that will help its user to identify and correct them. On the other hand, the code generator should not handle the unexpected error conditions in a way that would make troubleshooting them more difficult for its author. Complete discussion of error handling strategy is outside of scope of this article. More information on this subject is available in How to Design Exception Hierarchies by Krzysztof Cwalina and Fail Fast by Jim Shore.

This article reviews examples of error conditions in the code generator created earlier in this series and discusses how to handle them. As you remember, this generator (shown below) uses several templates that retrieve table schema information from a given SQL Server database using SMO and generate DELETE, INSERT and UPDATE stored procedures for each table. 

CrudProcedureGenerator.tt

<#@ assembly name="Microsoft.SqlServer.ConnectionInfo" #>
<#@ assembly name="Microsoft.SqlServer.Smo" #>
<#@ import namespace="Microsoft.SqlServer.Management.Smo" #>
<#@ include file="DeleteProcedureTemplate.tt" #>
<#@ include file="InsertProcedureTemplate.tt" #>
<#@ include file="UpdateProcedureTemplate.tt" #>
<#+
public class CrudProcedureGenerator : Generator
{
  public string DatabaseName;

  public DeleteProcedureTemplate DeleteTemplate = new DeleteProcedureTemplate();
  public InsertProcedureTemplate InsertTemplate = new InsertProcedureTemplate();
  public UpdateProcedureTemplate UpdateTemplate = new UpdateProcedureTemplate();

  protected override void RunCore()
  {
    Server server = new Server();
    Database database = new Database(server, this.DatabaseName);
    database.Refresh();

    // …
  }
}
#>

Below is an example of using this code generator to produce stored procedures for the Northwind database on the local computer. Complete source code of this example is available for download at the bottom of this article.

NorthwindStoredProcedures.tt

<#@ template language="C#" hostspecific="True" debug="True" #>
<#@ output extension="txt" #>
<#@ include file="T4Toolbox.tt" #>
<#@ include file="CrudProcedureGenerator.tt" #>
<#
    CrudProcedureGenerator generator = new CrudProcedureGenerator();
    generator.DatabaseName = "Northwind";
    generator.Run();
#>

Usage Errors

A typical error in using a complex code generator is forgetting to specify a required parameter, such as DatabaseName in our example. We can simulate this error by commenting out the line that assigns “Northwind” to generator.DatabaseName in NorthwindStoredProcedures.tt and saving the file which causes Visual Studio to run the code generator and display the following error.

As you can see, this error provides complete details about the exception that caused it and will help the author of the code generator to identify the problem quickly. Unfortunately, it does not help the user of the code generator, because it is too verbose and low-level. We can make it a lot more specific and helpful by adding the following code to CrudProcedureGenerator.tt.

<#@…#>
<#+
public class CrudProcedureGenerator : Generator
{
  public string DatabaseName;
  // …
  protected override void Validate()
  {
    if (string.IsNullOrEmpty(this.DatabaseName))
    {
      this.Error(
        "DatabaseName property of CrudProcedureGenerator must be assigned");
    }
  }
}
#>

Validate is a protected virtual method defined in the base class - Generator. When overridden in a concrete descendant class, such as CrudProcedureGenerator, this method can use Error and Warning methods of the Generator class to report errors and warnings. The Run method, also defined in the Generator class, will call the Validate method first. If Validate doesn’t report any errors, Run will call RunCore which CrudProcedureGenerator overrides to implement the actual code generation logic. And finally, Run will display any errors or warnings reported during code generation in the Error List window of Visual Studio. With added error-handling code, the following error message is displayed when we try to run the code generator without specifying DatabaseName. 

Template class of T4 Toolbox follows the same pattern to support error handling. This class also defines virtual Validate method as well as Error and Warning methods which can be used by concrete descendants to report errors and warnings.

Environment Errors

Code generators typically access external resources to obtain metadata for code generation. File system and database are perhaps the most common sources of metadata. In our example, we are accessing a database running on the local computer. While NorthwindStoredProcedures.tt may work perfectly for the developer who originally created it, another developer on the same team, might have SQL Server configured differently, perhaps using a named instance, which can prevent the same code generator from running on her computer. We can simulate this error by stopping the SQL Server service (using the “net stop mssqlserver” in Windows command prompt) and re-running the code generator (by selecting “Run Custom Tool” from the context menu of NorthwindStoredProcedures.tt in Solution Explorer of Visual Studio). 

Similar to the usage error we discussed earlier, this error is very verbose and low-level. We can make it more precise and useful for the users of the code generator by wrapping the original FailedOperationException, thrown by SMO in a TransformationException defined by the T4 Toolbox.

<#@…#>
<#+
public class CrudProcedureGenerator : Generator
{
  public string DatabaseName;
  // …
  protected override void RunCore()
  {
    try
    {
      Server server = new Server();
      Database database = new Database(server, this.DatabaseName);
      database.Refresh();
      // …
    }
    catch (FailedOperationException e)
    {
      throw new TransformationException(
        string.Format(
          "Unable to access {0} database on local SQL Server instance",
          this.DatabaseName),
        e);
    }
  }
  // …
}
#>

Run method of the Generator class will catch TransformationException and displays its Message in the Error List of Visual Studio.

In other words, instances of TransformationException class are considered to be expected exceptions, thrown by the code generator itself. Only error message is displayed for expected exceptions. All other exception types are treated as unexpected and will be displayed with complete stack trace.

Render method of the Template class also catches TransformationException instances and reports them as expected errors.

Unexpected Errors

Unexpected errors are, well, unexpected. The author of the code generator does not expect them to occur. When user of  the code generator encounters such an error, having complete details about it will help to troubleshoot and resolve the problem quickly. Allowing unexpected exceptions to simply bubble up unhandled will display their complete stack trace in the Error List of Visual Studio. On the other hand, trying to make the code generator more “robust” and “user-friendly” by catching all exceptions hides the exception stack trace and makes it more difficult to troubleshoot. It is best to catch only those exceptions that indicate error conditions you expect and can make specific recommendations to the user on how to resolve them.

Conclusion

By default, Visual Studio displays complete details for unhandled exceptions that occur during code generation in the Error List window. This makes them easier to troubleshoot for authors of code generators. Appropriate error handling can helps to make code generators easier for the users to use. T4 Toolbox defines TransformationException, which code generators can throw with a user-readable messages to indicate expected error conditions. Template and Generator classes catch exceptions of this type and display only the exception message in the Error List of Visual Studio. Both Template and Generator classes provide virtual Validate methods that descendants can override to implement validation of code generation parameters. Error and Warning methods are available in both base classes to report multiple errors and warnings.

Download

• Source code, initial
• Source code, completed

Code generation is an increasingly common technique in application development and forms a part of many Visual Studio extensions. With the addition of T4 to Visual Studio 2008, every developer has a powerful code generation engine available to them. In this session we’ll look at patterns of usage of T4 and ways to structure your templates for large-scale reuse. We’ll explore a sample that aids large scale code generation from DSL models and finally look at a community library which adds facilities to make the tricky problems of incremental code generation and reverse engineering from a DSL easier.

Gareth recently wrote that recording of this and other VSX sessions is now available on Channel 9.

Introduction

In the previous article of this series, we created CrudProcedureGenerator.tt – a reusable code generator that produces CRUD stored procedures for all tables in a given SQL Server database. Each type of stored procedure is produced by a separate template – DeleteProcedureTemplate.tt, InsertProcedureTemplate.tt or UpdateProcedureTemplate.tt. The Generator and Templates use SMO (SQL Server Management Objects) to retrieve table and column information from the database. We have also created a simple code generation file shown below to generate CRUD stored procedures for all tables in the Northwind sample database.

<#@ template language="C#" hostspecific="True" debug="True" #>
<#@ output extension="txt" #>
<#@ include file="T4Toolbox.tt" #>
<#@ include file="CrudProcedureGenerator.tt" #>
<#
    CrudProcedureGenerator generator = new CrudProcedureGenerator();
    generator.DatabaseName = "Northwind";
    generator.Run();
#>

In its current form, this code generation solution will work well for producing CRUD stored procedures in a single application development project. This article will illustrate how it can be reused across multiple projects and multiple teams.

Source control

It is important to keep both generated source code and code generation files under source control. During initial development of the code generation solution, the code generation files are typically stored side-by-side with the generated files.

However, as soon as the code generation files need to be reused outside of the original project where they were developed, they need to be stored separately and treated as a separate project.

Separate code generation files from project files

• Create a new folder called CodeGeneration and move reusable code generation files from the original project folder into the new folder.

Note that NorthwindStoredProcedures.tt remained in its original location. This file relies on reusable code generation files to generate SQL scripts specific to a particular project, Northwind database in this example. In other words, NorthwindStoredProcedures.tt is project-specific and should be stored with the rest of this project’s source code.

Use relative file paths

It is important to rely on relative file paths in team environment to allow for differences in computer configurations of different team members. However, after moving reusable code generation files out of their original location, we will get an error trying to regenerate NorthwindStoredProcedures.tt.

As you can see in the source code of NorthwindStoredProcedures.tt at the top of this article, it uses include directive with a relative path to pull in the contents of CrudProcedureGenerator.tt. Although we can fix the immediate problem by changing the NorthwindStoredProcedures.tt to refer to CrudProcedureGenerator.tt as “..\CodeGeneration\CrudProcedureGenerator.tt”, support for relative file paths in the include directive is limited just one level of nesting and it will not be able to find DeleteProcedureTemplate.tt, IncludeProcedureTemplate.tt and UpdateProcedureTemplate.tt included by CrudProcedureGenerator.tt. We can work around this limitation by adding path to shared code generation files to the list of known IncludeFolders.

• Add IncludeCodeGeneration string value to the HKLM\Software\Microsoft\VisualStudio\9.0\TextTemplating\IncludeFolders\.tt registry key. Enter full path to the CodeGeneration folder as the value data.

Visual Studio will attempt to resolve relative file paths used in the include directive by combining them with the known IncludeFolders. As long as each developer working on the project has the path to the CodeGeneration folder added to the registry, they will be able to use the shared code generation files without having to modify them or using absolute paths in files themselves.

Reusing code generator on another project

At this point, all we need to start using CrudProcedureGenerator on another project is create a code generation file similar to NorthwindStoredProcedures.tt and specify a different database in it.

<#@ template language="C#" hostspecific="True" debug="True" #>
<#@ output extension="txt" #>
<#@ include file="T4Toolbox.tt" #>
<#@ include file="CrudProcedureGenerator.tt" #>
<#
    CrudProcedureGenerator generator = new CrudProcedureGenerator();
    generator.DatabaseName = "pubs";
    generator.Run();
#>

The resulting structure of folders and projects in your solution may look as shown on the right. Complete source code is available for download at the bottom of the article.

Reusing code generator on another team

In this article we assumed that both projects using the shared code generator are stored in the same source control repository. This may be the case when the same team is working on both projects. If separate teams are working on these projects, they may be using separate source control repositories. Only one repository should be used for development and maintenance of the code generation files. This repository stores the “master” copy of the code generation files. Other teams will typically store a copy of these files in their own source control repository to preserve complete source code history of their project. As improvements are made to the master copy, other teams can upgrade their copy when it’s appropriate for their project.

Download

• Source code, initial
• Source code, completed

Introduction

In the previous article of this series, we created a reusable code generation template called DeleteProcedureTemplate that generates a DELETE stored procedure for a given database table using SMO. We have also created a simple code generation file shown below to generate a DELETE procedure for the Products table in the Northwind database.

<#@ template language="C#" hostspecific="True" #>
<#@ output extension="sql" #>
<#@ include file="T4Toolbox.tt" #>
<#@ include file="DeleteProcedureTemplate.tt" #>
<#
    DeleteProcedureTemplate template = new DeleteProcedureTemplate();
    template.DatabaseName = "Northwind";
    template.TableName = "Products";
    template.Render();
#>

In its current form, this code generator has several drawbacks. Extending this file to generate stored procedures for multiple tables will produce a single large SQL script, which becomes increasingly difficult to work with. On the other hand, creating similar files to generate additional stored procedures in separate files results in code duplication and increases the number of the code generation files themselves. Ideally, we want to generate all CRUD stored procedures for a given set of database tables in separate SQL scripts. Let’s see how we can accomplish that using T4 Toolbox.

Creating a new code generator

• Continue using the C# project you created previously or download the initial source code below.
• Click Project->Add New Item in the main menu and select Generator item from the Code Generation folder in the dialog. If you don’t see this folder or this item, make sure you have the latest version of T4 Toolbox installed.

• Enter CrudProcedureGenerator.tt as the item name and click the Add button.
• Double-click CrudProcedureGenerator.tt in the Solution Explorer. You will see the following text in the editor.

<#+
// <copyright file="CrudProcedureGenerator.tt" company="Your Company">
//  Copyright © Your Company. All Rights Reserved.
// </copyright>

public class CrudProcedureGenerator : Generator
{
    protected override void RunCore()
    {

    }
}
#>

This file contains a class feature block that defines a class called CrudProcedureGenerator. It inherits from a base class Generator, which is defined in T4 Toolbox. Similar to the template class definition we talked about in the previous article, this file is not intended to be used for code generation directly. Instead it will be reused by other code generation files, as we will see shortly.

• Select DeleteProcedureTemplate.tt in the solution explorer and change Custom Tool property from TextTemplatingFileGenerator to an empty value. This will prevent Visual Studio from trying to use this file for code generation and reporting errors in the Error List window.

Encapsulate code generation logic in the generator class

Generator base class defines an abstract method called RunCore. Each concrete generator must override this method and implement the code generation logic inside of it. A concrete generator typically uses one or more templates to generate one or more output files.

• Modify CrudStoredProcedureGenerator.tt to look like this:

<#@ assembly name="Microsoft.SqlServer.ConnectionInfo" #>
<#@ assembly name="Microsoft.SqlServer.Smo" #>
<#@ import namespace="Microsoft.SqlServer.Management.Smo" #>
<#@ include file="DeleteProcedureTemplate.tt" #>
<#+
public class CrudProcedureGenerator : Generator
{
    public string DatabaseName;
    public DeleteProcedureTemplate DeleteTemplate = new DeleteProcedureTemplate();

    protected override void RunCore()
    {
        Server server = new Server();
        Database database = new Database(server, this.DatabaseName);
        database.Refresh();
        foreach (Table table in database.Tables)
        {
            this.DeleteTemplate.DatabaseName = this.DatabaseName;
            this.DeleteTemplate.TableName = table.Name;
            this.DeleteTemplate.RenderToFile(table.Name + "_Delete.sql");
        }
    }
}
#>

Note that this class defines a public field, DatabaseName, to allow the caller to specify a database for which stored procedures need to be generated. It also defines a public field, DeleteTemplate, which is initialized with a DeleteProcedureTemplate instance. The RunCore method retrieve the list of all tables in a database with the specified DatabaseName and generates a DELETE stored procedure for each table with the help of the DeleteTemplate. Thanks to the RenderToFile method, which is defined in the Template base class, each stored procedure is generated in a separate SQL file.

Reuse the code generator

Having the logic necessary to generate DELETE stored procedures for multiple tables encapsulated in the CrudProcedureGenerator class, we can now start using this generator on one or more application development projects to generate stored procedures for different databases.

• Click Project->Add New Item in the main menu and select File item from the Code Generation folder in the dialog.
• Name the new file NorthwindProcedures.tt and change its contents to look similar to this.

<#@ template language="C#" hostspecific="True" debug="True" #>
<#@ output extension="txt" #>
<#@ include file="T4Toolbox.tt" #>
<#@ include file="CrudProcedureGenerator.tt" #>
<#
    CrudProcedureGenerator generator = new CrudProcedureGenerator();
    generator.DatabaseName = "Northwind";
    generator.Run();
#>

This code generation file uses include directive to pull in the contents of CrudProcedureGenerator.tt and a statement block to create a new instance of the CrudProcedureGenerator class. It specifies value for the DatabaseName field of the generator and calls its Run method. Run method calls the RunCore method we implemented previously, with additional validation checks and error handling.

• Save NorthwindStoredProcedures.tt - Visual Studio will compile and run the code generator. Be patient, it can take a while for the code generator to retrieve metadata from a “cold” database.
• Click the “+” sign next to the NorthwindStoredProcedures.tt in Solution Explorer. You will see a number of SQL files nested under it, each with a single DELETE stored procedure for a particular database table.

At this point, we have a generator that produces stored procedures for all tables in the Northwind database. We can reuse this generator on another project by creating another code generation file, such as AdventureWorksStoredProcedures.tt that specifies a different database name to generate stored procedures for. It would be straightforward to implement additional templates for SELECT, INSERT and UPDATE procedures and extend our generator to incorporate them. We could also improve the generator by allowing the caller to define a subset of tables that need stored procedures using a wildcard or a regular expression. However, these enhancements are outside of the scope of this tutorial and are left for the readers to complete.

Conclusion

This article showed how to create a complex generator, which uses one or more templates to generate multiple output files of different types. This generator is easy to manage, as it generates all outputs for the given input. It can also be easily reused without introducing code duplication.

The next article will discuss reusing code generators on multiple projects and multiple teams.

Download

• Source code, initial.
• Source code, completed.

Introduction

In the first article of this series, we created the following code generation file to generate a DELETE stored procedure for a given database table using SMO. This stored procedure is one of the CRUD procedures that would need to be created to encapsulate access to a particular database table. Accessing data exclusively through CRUD stored procedures helps to eliminate SQL injection vulnerabilities, prevent accidental data corruption during casual browsing and may help to improve performance of SQL queries.

<#@ 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();
#>    

Note that this file has code generation parameters (database name and table name) embedded in its source code. In order to reuse this code generator in its current form, we would need to create a copy of this file and modify the embedded parameters to specify another database and table names. While this approach certainly works for simple code generators that need to be used a limited number of times, it creates code duplication and makes maintaining code generators more and more difficult.

We also need to extend this code generator to create additional types of stored procedures to encapsulate INSERT, UPDATE and SELECT SQL statements. We could accomplish that by extending this file to generate all of these stored procedures. Again, this approach works well for a simple code generator, but as the number of procedures this template generates grows, it becomes more and more difficult to manage.

Let’s see how we can extend this code generator without introducing code duplication and additional complexity.

Create a new code generation template

Let’s define code generation template (or simply template) as a reusable code generator, which produces a single logical unit of code. In our example, the template will generate a delete stored procedure for a single database table.

• Create a new C# Class Library project in Visual Studio.
• Click Project->Add New Item in the main menu and select Template item from the Code Generation folder in the dialog. If you don’t see this folder or this item, make sure you have the latest version of T4 Toolbox installed.

• Enter DeleteProcedureTemplate.tt as the item name and click the Add button.
• Double-click DeleteProcedureTemplate.tt in the Solution Explorer. You will see the following text in the editor.

<#+
// <copyright file="DeleteProcedureTemplate.tt" company="Your Company">
//  Copyright © Your Company. All Rights Reserved.
// </copyright>

public class DeleteProcedureTemplate : Template
{
    protected override void RenderCore()
    {

    }
}
#>

This file contains a class feature block that defines a template class called DeleteProcedureTemplate. It inherits from a base class called Template, which is defined in T4 Toolbox. Although this file has a .tt extension, it is not intended to be used for code generation directly. Instead it will be reused by other code generation files, as we will see shortly. In the mean time, note that Visual Studio displays an error when trying to process this file.

• Select DeleteProcedureTemplate.tt in the solution explorer and change Custom Tool property from TextTemplatingFileGenerator to an empty value.

TextTemplatingFileGenerator is a custom tool that invokes the code generation Engine to run or transform the code generation file. Clearing the Custom Tool property of the code generation file prevents Visual Studio from trying to process the file and displaying the unnecessary error.

Encapsulate code generation logic in the template class

Template base class defines an abstract method called RenderCore. Each concrete template must override this method and implement code generation logic inside of it.

• Copy the contents of the original file inside of the RenderCore method in DeleteProcedureTemplate.tt and modify it to look like this:

<#@ assembly name="Microsoft.SqlServer.ConnectionInfo" #>
<#@ assembly name="Microsoft.SqlServer.Smo" #>
<#@ import namespace="Microsoft.SqlServer.Management.Smo" #>
<#+
public class DeleteProcedureTemplate : Template
{
    public string DatabaseName;
    public string TableName;

    protected override void RenderCore()
    {
        Server server = new Server();
        Database database = new Database(server, DatabaseName);
        Table table = new Table(database, TableName);
        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();
    }
}
#>

Note that code generation parameters database name and table name are now encapsulated as public fields in the DeleteProcedureTemplate class. These fields are used inside of the RenderCore method to retrieve table metadata information and generate the stored procedure with the help of text blocks, expression blocks and class feature blocks.

Reuse the code generation template

Having the code generation logic encapsulated in a template class, we can now reuse it in another code generation file without duplicating the code.

• Click Project->Add New Item in the main menu and select File item from the Code Generation folder in the dialog.
• Name the new file Products_Delete.tt and change its contents to look similar to this.

<#@ template language="C#" hostspecific="True" #>
<#@ output extension="sql" #>
<#@ include file="T4Toolbox.tt" #>
<#@ include file="DeleteProcedureTemplate.tt" #>
<#
    DeleteProcedureTemplate template = new DeleteProcedureTemplate();
    template.DatabaseName = "Northwind";
    template.TableName = "Products";
    template.Render();
#>

This code generation file uses include directive to pull in the contents of DeleteProcedureTemplate.tt. It then uses a statement block to create a new instance of the DeleteProcedureTemplate class; assigns database name and table name values and calls the Render method of the template object. Render method ultimately calls the RenderCore method with additional validation checks and exception handling.

• Open Products_Delete.sql generated by this file.

create procedure Products_Delete
    @ProductID int
as
    delete from Products
    where
        ProductID = @ProductID

At this point we have a delete procedure for the Products table generated by the code generation file Products_Delete.tt with the help of the template defined in DeleteProcedureTemplate.tt. We can continue reusing the template by creating similar code generation files to produce delete procedures for other tables - Customers_Delete.tt, Orders_Delete.tt, etc. We can also create additional templates - InsertProcedureTemplate, UpdateProcedureTemplate, etc. to generate remaining types of CRUD stored procedures.

Conclusion

We have encapsulated logic for generating a DELETE stored procedure as a reusable template, which we can now reuse to generate multiple stored procedures without duplicating the code generation logic. However, table-specific code generation files like Products_Delete.tt and Customers_Delete.tt still contain a lot of duplication - 9 out of 10 lines required to render the template in each file are the same. Another problem with the current version is having a separate code generation file for each stored procedure. Combined with insert, update and select stored procedures, the total number of code generation files becomes difficult to manage even for a simple database like Northwind.

We will address these problems in the next article, by creating a composite code generator that produces multiple types of stored procedures for a given database tables or multiple tables in a given database.

Download

Source code, completed.

Overview

As you remember from the previous article in this series, Runtime Errors are caused by exceptions thrown by code in the GeneratedTextTransformation class, which is compiled and executed by the code generation Engine.

Although the Engine reports detailed stack dump for every exception thrown, troubleshooting non-trivial runtime errors may require using a debugger to step through the template code as it executes. Because template code is running inside of Visual Studio process itself, a second instance of Visual Studio is required to serve as a debugger for the first instance, which is running the template code.

Current support for debugging of code generation templates in Visual Studio is somewhat limited. It requires you to either use a manual breakpoint in the template code to trigger the just-in-time debugger or starting a debugging instance of Visual Studio in advance and attaching it to the instance that’s running the template.

Setup

Use Visual Studio to open CrudStoredProcedures.tt created in the first 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();
#>    

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

• 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.

Just-In-Time Debugging

The quickest way to start debugging is by placing a breakpoint in the code of the template and triggering the just-in-time debugger. Note, if you are using Windows Vista, this technique can hang Visual Studio. Please read the Just In Time Debugging on Windows Vista section below first.

• Modify the template to call Debugger.Break method in the beginning of the code block.

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

Debugger.Break method attempts to launch the Just-In-Time Debugger configured on your system.You should see a Visual Studio Just-In-Time Debugger dialog (shown above).

• In Visual Studio Just-In-Time Debugger dialog, select New instance of Visual Studio 2008 in the list and click Yes.

This will launch a new instance of Visual Studio and attach it as a debugger to the first instance which is running your template. You should see the source code of your template automatically loaded in debugger and a green line pointing where the execution point currently is.

While in debugger, you can use all standard features, like stepping through code, and windows, like Watch, Call Stack, Immediate, etc.

• Select Exceptions item from Debug menu in Visual Studio; turn on the option to break when exception is thrown and click OK.

• Select Continue item from Debug menu in Visual Studio.

The template will continue to run until it encounters the exception. At that point, the Visual Studio debugger will pause it and display the dialog shown above. You can inspect the exception object by clicking View Detail link.

• Select Continue item from Debug menu.
• Close the debugging instance of Visual Studio.
• Back in the original instance of Visual Studio, remove the call to Debugger.Break method from the template code.

Just-In-Time Debugging on Windows Vista

By default on Windows Vista, the just-in-time debugger is configured to display a user-friendly dialog shown below. Although you can click the Debug the program button and start the debugger successfully, your original Visual Studio instance will hang in the end of the debugging session.

In order to avoid having to constantly kill the Visual Studio process after debugging, you will want to change Just-In-Time debugger configuration to work the same way it does on Windows XP and Windows Server 2003. This configuration is stored in registry as DbgJITDebugLaunchSetting value in HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\.NETFramework key. It’s default value on Windows Vista is 0×10. Change it to 0×2, which is the default value on Windows XP. After making this change, you should no longer see the User-Defined Breakpoint dialog and will be able to continue using Visual Studio after debugging.

Attaching Debugger Manually

Just-in-time debugging, described above, is the fastest and most precise way to set a breakpoint in template code and hit it in the debugger. However, it may not be appropriate if the code generation file you want to debug is read-only (such as when it is stored in source control repository or received from a third-party). In this situation, you can attach the debugger manually, which takes longer but doesn’t require you to modify the template code.

• Start a second instance of Visual Studio and open the code generation file you need to debug - CrudStoredProcedures.tt in this example.
• Select Attach to Process from the Debug menu in Visual Studio.

• In the list of Available Processes, select devenv.exe and click the Attach button. This will attach the current instance of Visual Studio as a debugger for the first instance of Visual Studio running the template. Let’s call the first instance as simply Visual Studio and the second instance as Debugger.
• Back in text editor of the Debugger, where you have the CrudStoredProcedures.tt file open, click on the left side of line 8 to sent a breakpoint.

Normally, the red breakpoint icon would appear next to the line you clicked. However, due to limitations in the current support for template debugging, Visual Studio displays the breakpoint icon in line 2 instead.

• In the original Visual Studio instance, trigger template transformation by either saving the template or selecting Run Custom Tool from the context menu in Solution Explorer. This will trigger the breakpoint and you will see something like this in the Debugger.

You can use all debugging features as you would expect in regular .NET code with the exception of breakpoints. I have not found a way to place breakpoints in the template code precisely using the debugger and have to resort to manual breakpoints using Debugger.Break as described above.

• Select Continue item from Debug menu.
• Close the debugging instance of Visual Studio.
• Back in the original instance of Visual Studio, restore the original initialization code for server variable shown in the source code at the beginning of this article.

Conclusion

Debugging is the most powerful technique in troubleshooting runtime errors that occur during code generation. Although current support for debugging of template code in Visual Studio is somewhat limited, you can debug templates effectively by either triggering Just-In-Time debugger with Debugger.Break from template code or by attaching a separate instance of Visual Studio as a debugger in advance.

In the next article of this series, we will talk about creating reusable code generation templates.

While SharePoint does have the one-button install option, it isn’t a monolithic application that just gets dropped on a server. SharePoint has a number of moving pieces that should be understood by both infrastructure and application architects. In this session, we’ll review the architectural makeup of SharePoint’s infrastructure, as well as the components of a custom SharePoint solution. A thoughtfully-designed SharePoint architecture can be the difference between smashing success and humiliating failure.

Speaker

David McNamee, SharePoint Technical Specialist, Microsoft Corp.

When

Thursday, September 25, 2008
6:30 PM - 8:30 PM
Pizza: 6:00 PM - 6:30 PM

Location

Kforce, 1001 East Palm Avenue, Tampa, FL 33605
Map, Directions

Registration

Click here to register.

About IASA

Established in 2002, IASA (International Association of Software Architects) is an international non-profit business association dedicated to the advancement and sharing of issues related to software architecture in the enterprise, product, education and government sectors. The association is committed to improving the quality of the IT architecture industry by developing and delivering standards, education programs and developing accreditation programs and services that optimize the development of architecture profession.

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.

In this series of articles, we will create a code generator produces CRUD stored procedures for tables in a SQL Server database. In the examples, we will be using the Northwind sample database.

Creating a Code Generation File

• Create a new C# Class Library project in Visual Studio.
• Click Project->Add New Item in the main menu and select Code Generation->File template in the dialog.

• Enter CrudStoredProcedures.tt as the item name and click the Add button.
• Double-click the new file in the Solution Explorer. You will see the following text in the text editor.

<#@ template language="C#" hostspecific="True" debug="True" #>
<#@ output extension="txt" #>
<#@ include file="T4Toolbox.tt" #>
<#
// <copyright file="CrudStoredProcedures.tt" company="Your Company">
//  Copyright © Your Company. All Rights Reserved.
// </copyright>

#>

This file is a Text Template, also known as a T4 Template. Text Templates are code generators that can be used to generate any text files, including C#, Visual Basic, SQL and XML. Text Templates use ASP.NET-like syntax and consist of text blocks, code blocks and directives. Text blocks are blocks of text in the template that are copied to the output file as is. Directives provide instructions to the text templating Engine on how to process the template. In the example above, template directive tells the Engine that this template uses C# in code blocks. Code blocks contain C# or Visual Basic code that runs during template transformation and allow making generated output dynamic.

Generating Static Output

We will start implementing our code generator by hard-coding DELETE stored procedure for the Products table of Northwind database.

• Change CrudStoredProcedures.tt to look like so.

<#@ output extension="SQL" #>
create procedure Products_Delete
    @ProductID int
as
    delete from Products
    where ProductID = @ProductID

When you save CrudStoredProcedures.tt, the text templating Engine transforms it to generate the output file. In the Solution Explorer, the output file appears nested under the the file. You can also transform the file by right-clicking it in the Solution Explorer and selecting "Run Custom Tool" from the context menu. If you have multiple text templates in your project, you can transform them all by clicking "Transform All Templates" button in the toolbar.

In the template above, the text block is shown in gray. If you double-click the generated file, its contents will be identical to the contents of the text block and will look like so.

create procedure Products_Delete
    @ProductID int
as
    delete from Products
    where ProductID = @ProductID

At this point, the generated output is static, which is not any better than coding this stored procedure by hand. Instead, we can generate it dynamically, using database schema information provided by SQL Server.

Adding .NET code to text template

• Change CrudStoredProcedures.tt to look like so

<#@ 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 Products_Delete
    @ProductID int
as
    delete from Products
    where ProductID = @ProductID

This code uses template directive to specify that this template uses C# in its code blocks.  This template contains a statement block which is defined using special markers - <# and #>. This block uses SQL Server Management Objects (SMO) to retrieve metadata information about Products table from the Northwind database running on the local SQL server instance. This API (SMO) is defined in a .NET assembly, Microsoft.SqlServer.Smo which is installed in the Global Assembly Cache by SQL Server setup program. In order to use this API, this template uses an assembly directive to reference the assembly where it is defined and an import directive to specify the namespace where Server, Database and Table types are defined without having to use fully-qualified type names.

Making Code Generation Dynamic

Having metadata information about the target table, we can now generate the DELETE stored procedure dynamically.

• Change CrudStoredProcedures.tt to look like so.

<#@ 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();
#>    

This template uses expression blocks to dynamically generate name of the target table in the output file. Expression blocks are defined using special markers - <#= and #> and can contain any valid programming expression, which will be converted to string and written to the output file. This template also uses additional statement blocks to iterate through the list of Columns and calls WriteLine method to generate stored procedure parameter declarations and WHERE clause for the DELETE statement based on the primary key of the table. PushIndent and PopIndent methods are used to format parameter declarations and the where clause.

Conclusion

The text template shown in this article generates a single DELETE stored procedure based on table schema information retrieved from SQL Server using SMO. In the next article, we will talk about troubleshooting code generation errors.

At the same time, I also had a thought in my mind that my blog doesn’t offer much help to people who are only getting started with T4 and code generation. I cover this information in my talks, but most of my readers are located outside of Florida and don’t have the opportunity to hear them.

Finally, some of the articles I wrote early on are becoming outdated and many of them are more complicated than necessary. OK, some of them are a lot more complicated than a template developer needs..

To address these issues, I am starting a short series of posts about code generation with text templates in Visual Studio. This series will cover a range of topics, starting with basics and ending with advanced topics, such as design of templates and code generators. It will be based on T4 Toolbox to take advantage of the framework it provides for generating multiple output files and integration with Visual Studio. As this series is targeted at a template developer, it will not cover the finer points of T4 Architecture.  It will cover some of the topics discussed by the T4 Template Design mini-series. However, instead of describing all of the various ways you could design your templates, it will focus on the approach I believe to be the best and have chosen for T4 Toolbox.

I hope you find this series useful. As always, I would like to hear from you.  Please post a comment or send me an email if you find this information useful, if you have a specific question or suggestion. A simple attaboy is always appreciated.