编写T4模板进行代码生成

本篇文章介绍的是两个重要的话题：程序集锁定和调试。

目录
一、程序集引用导致的编译问题
二、T4引擎对引用程序集的锁定
三、Debugger.Break导致VS 2010的Crash
四、在Debugger.Break之前加上Debugger.Launch

一、程序集引用导致的编译问题

为了让读者对“程序集锁定”，以及由它造成的开发上的不便有一个深刻的认识，我特意写了一个小例子。如右图所示的解决方案包含两个项目：Lib和T4。其中我们的T4项目中定义了一个叫作HelloWorld.tt的模板文件，该文件需要使用到定义在Lib项目中的某个类型。所以，HelloWorld.tt模板文件中需要通过<#@Assembly…#>指令引用Lib项目编译生成的程序集（Artech.T4Template.Lib.dll）。

如果你看过我上一篇文章，你应该知道我们至少具有解决T4模板的程序集引用的五种方案，在这里我们采用的是VS宏的解决方案，即将引用程序集文件的路径设置成通过$(SolutionDir)表示的解决方案目录的相对路径。HelloWorld.tt定义如下，引用的程序集路径为Lib项目在Debug模式下编译生成的目录（$(SolutionDir)Lib\Bin\Debug\）。

<#@ template debug="true" hostSpecific="true" #>

<#@ output extension=".cs" #>

<#@ Assembly name="$(SolutionDir)Lib\Bin\Debug\Artech.T4Template.Lib.dll" #>

using System;

public class HelloWord

{

    static void Main()

    {    

        <# foreach( var person in Artech.T4Template.HelloWorldHelper.GetPersons())

        {#>

        Console.WriteLine("Hello, {0}!", "<#=person#>");    

        <# } #>

    }

}

当你保存该T4模板，T4引擎将触发并进行代码生成工作，但是此时如果你试图编译被引用（实际上是生成的程序集被引用）的Lib项目，将会出现如下所示的编译错误。错误信息为：“Unable to copy file "obj\Debug\Artech.T4Template.Lib.dll" to "bin\Debug\Artech.T4Template.Lib.dll". The process cannot access the file 'bin\Debug\Artech.T4Template.Lib.dll' because it is being used by another process.”，即之前生成的程序集正在被使用，所以不能将生成的程序集拷贝到编译目标目录下。

二、T4引擎对引用程序集的锁定

实际上这个程序集的使用者正是T4引擎。出于提高性能考虑，T4引擎在进行基于代码生成的模板转换（Template Transformation）的时候，会始终重用同一个AppDomain。由于该AppDomain不会自动卸载，这就会导致该AppDomain始终锁定所有被它加载的程序集。如果我们需要释放程序集，我们不得不重启VS。但是，对于T4模板的开发调试阶段，这种通过重新启动VS的方式去释放程序集以确保我们的项目能够成功编译是不能接受的。

那么，是否有一种解决方案既能够确保T4引擎能够进行正常的模板转换，又能避免它强行锁定引用程序集呢？如果你采用T4 ToolBox，你可以通过<#@ VolatileAssembly…#>这个指令轻松地解决这个问题。下面的T4模板中，我们将通过<#@Assembly…#>指令的程序集引用方式替换成了<#@ VolatileAssembly…#>（<#@ VolatileAssembly processor="T4Toolbox.VolatileAssemblyProcessor"  name="$(SolutionDir)Lib\Bin\Debug\Artech.T4Template.Lib.dll" #>），我们的Lib项目在任何时候都可以自由地编译。

<#@ template debug="true" hostSpecific="true" #>

<#@ output extension=".cs" #>

<#@ VolatileAssembly processor="T4Toolbox.VolatileAssemblyProcessor"  name="$(SolutionDir)Lib\Bin\Debug\Artech.T4Template.Lib.dll" #>

using System;

public class HelloWord

{

    static void Main()

    {    

        <# foreach( var person in Artech.T4Template.HelloWorldHelper.GetPersons())

        {#>

        Console.WriteLine("Hello, {0}!", "<#=person#>");    

        <# } #>

    }

}

<#@ VolatileAssembly…#>的实现原理其实挺简单的，就是在加载的时候并不是直接加载指定的源程序集，而是创建一个新的程序集拷贝。

三、Debugger.Break导致VS 2010的Crash

VS和一些T4编辑器虽然给了基本的智能感知支持，但是在绝大部分我们相当于在编写纯文本的脚本，所以对于一些比较复杂的模板转换逻辑，我们需要通过Debug的方式去发现一些无法避免的问题。关于T4模板的Debug，你Google一下会搜出一大堆。在这些“大众化”的Debug解决方案中都包含两点：

• 在<#@ template…#>指令中将debug属性设置为true；
• 在需要设置断点的地方执行Debugger.Break方案

按照这两点，我们改写了我们的T4模板，在foreach语句之前加上<# Debugger.Break(); #>，并通过<#@import…#>指令导入System.Diagnostics命名空间。我不知道在VS 2008下这种解决方案是否可行，但是如果你使用的是VS 2010，这肯定会导致整个VS的崩溃。当你保存TT文件的时候，如右图所示的对话框弹出来，随之伴随整个VS的Crash。

<#@ template debug="true" hostSpecific="true" #>

<#@ output extension=".cs" #>

<#@ VolatileAssembly processor="T4Toolbox.VolatileAssemblyProcessor"  name="$(SolutionDir)Lib\Bin\Debug\Artech.T4Template.Lib.dll" #>

<#@ import namespace="System.Diagnostics" #>

using System;

public class HelloWord

{

    static void Main()

    {    

        <# Debugger.Break(); #>

        <# foreach( var person in Artech.T4Template.HelloWorldHelper.GetPersons())

        {#>

        Console.WriteLine("Hello, {0}!", "<#=person#>");    

        <# } #>

    }

}

四、在Debugger.Break之前加上Debugger.Launch

为了避免Debugger.Break导致的VS崩溃，只需要在之前多加一句代码即可，既Debugger.Launch。为此我们对我们的T4模板略加修改

<#@ template debug="true" hostSpecific="true" #>

<#@ output extension=".cs" #>

<#@ VolatileAssembly processor="T4Toolbox.VolatileAssemblyProcessor"  name="$(SolutionDir)Lib\Bin\Debug\Artech.T4Template.Lib.dll" #>

<#@ import namespace="System.Diagnostics" #>

using System;

public class HelloWord

{

    static void Main()

    {    

        <# 

        Debugger.Launch();

        Debugger.Break();

        foreach( var person in Artech.T4Template.HelloWorldHelper.GetPersons())

        {#>

            Console.WriteLine("Hello, {0}!", "<#=person#>");    

        <#} #>

    }

}

现在如果你保存该TT文件，VS会弹出如下一个对话框让你选在是否进行Debug。如果需要进行Debug，选择“Yes, debug devenv.exe”。

然后创建一个新的VS实例，或者选择已经打开的VS程序进行Debug，这个对话框我们应该很熟悉。最后程序将会执行到我们设置的断点（Debugger.Break），我们就可以像Debug普通托管程序一样对T4模板进行Debug了。实际上，你也可以直接通过Attach进程的方式进行Debug,不过这里的进程就是VS的进程devenv.exe。

VS 2010采用了与VS2008不同的程序集引用的解析机制。本篇文章为你介绍在VS2010下5种不同的程序集引用的方式。

目录
一、添加程序集引用解决不了问题
二、将引用程序集安装到GAC
三、利用VS的PublicAssemblies目录
四、指定程序集的具体路径
五、采用环境变量
六、使用VS宏

一、添加程序集引用解决不了问题

如果你的T4模板需要调用一个自定义的类型，并且该类型定义在某个非系统程序集中，你就需要通过T4<#@ assembly…#>指令引用该程序集。在VS 2008环境下，你只需要为当前项目添加相应的程序集引用，并且通过<@ assembly…#>指令的name属性指定程序集（Dll）的文件名即可。比如，下面的T4模板包含了对程序集Artech.T4AssemblyRefResovle.Foo.dll的引用。

<#@ template debug="false" hostspecific="false" language="C#" #>

<#@ assembly name="Artech.T4AssemblyRefResovle.Foo.dll" #>

<#@ output extension=".cs" #>

public class HelloWorld

{}

但是这种方式对于VS 2010则行不通，因为T4引擎在解析和编译模板的时候并不会从项目引用列表中去定位目标程序集。所以，对于上面的T4模板，会出现如下的编译错误。

二、将引用程序集安装到GAC

其实我们有很多方式来解决这个问题，你首先想到的肯定是将引用的程序集安装到GAC中。没错，这是一种解决方案，如果被引用的程序集具有强签名的话。有一点需要注意的是，T4模板引用某个安装于GAC的程序集的时候，在<#@ assembly…#>指令下不能指定文件扩展名（.dll)。T4模板应该按照如下的方式定义。

<#@ template debug="false" hostspecific="false" language="C#" #>

<#@ assembly name="Artech.T4AssemblyRefResovle.Foo" #>

<#@ output extension=".cs" #>

public class HelloWorld

{}

三、利用VS的PublicAssemblies目录

为了让T4引擎能够找到引用的程序集，你可以将其拷贝到VS 2010的PublicAssemblies目的下，该目录为C:\Program Files (x86)\Microsoft Visual Studio 10.0\Common7\IDE\PublicAssemblies。如果将Artech.T4AssemblyRefResovle.Foo.dll拷贝到该目录下，你在T4模板的<#@ assembly…#>指令下就可以直接指定程序集名称（不包括扩展名）或者程序集文件名（包括扩展名）。

<#@ template debug="false" hostspecific="false" language="C#" #>

<#@ assembly name="Artech.T4AssemblyRefResovle.Foo" #>

<#@ output extension=".cs" #>

public class HelloWorld

{}

指定文件扩展名

<#@ template debug="false" hostspecific="false" language="C#" #>

<#@ assembly name="Artech.T4AssemblyRefResovle.Foo.dll" #>

<#@ output extension=".cs" #>

public class HelloWorld

{}

四、指定程序集的具体路径

如果被引用的程序集被没有被签名，GAC的方式则不能使用，在这种情况下你需要指定程序集文件所在的位置，最直接的当然就是指定程序集文件的绝对路径。在下面的T4模板中，<#@ assembly…#>指令中指定的就是Artech.T4AssemblyRefResovle.Foo.dll文件的绝对路径。

<#@ template debug="false" hostspecific="false" language="C#" #>

<#@ assembly name="D:\T4AssemblyRefResovle\Lib\Artech.T4AssemblyRefResovle.Foo.dll" #>

<#@ output extension=".cs" #>

public class HelloWorld

{}

五、采用环境变量

采用程序集文件的绝对路径这种硬编码并不是一种推荐的解决方案，因为在团队开发中，每个开发人员用于存放同一个程序集的地址可能不同，在这种情况下你可以采用环境变量的方式。你可以定义个环境变量（比如FooDir）表示本机用于保存程序集的目录（比如D:\T4AssemblyRefResovle\Lib），那么被引用的程序集就可以表示成：%FooDir%\Artech.T4AssemblyRefResovle.Foo.dll.

<#@ template debug="false" hostspecific="false" language="C#" #>

<#@ assembly name="%FooDir%\Artech.T4AssemblyRefResovle.Foo.dll" #>

<#@ output extension=".cs" #>

public class HelloWorld

{}

六、使用VS宏

如果被引用的程序集所在目录是在当前解决方案或者当前项目的子目录（这是一种很常见的公共程序集保存方式），你还可以通过VS的宏命令来指定该目录。比如我们的Artech.T4AssemblyRefResovle.Foo.dll保存在当前解决方案目录的Lib子目录下，该程序集的路径就可以表示成：$(SolutionDir)\Lib\Artech.T4AssemblyRefResovle.Foo.dll。

<#@ template debug="false" hostspecific="false" language="C#" #>

<#@ assembly name="$(SolutionDir)\Lib\Artech.T4AssemblyRefResovle.Foo.dll" #>

<#@ output extension=".cs" #>

public class HelloWorld

{}

注：上面提到的程序集引用解决方案来源于《T4 Template error - Assembly Directive cannot locate referenced assembly in Visual Studio 2010 project.》

我们最常用的代码生成当时不是CodeDOM，而是T4，这是一个更为强大，并且适用范围更广的代码生成技术。今天，我将相同的例子通过T4的方式再实现一次，希望为那些对T4不了解的读者带来一些启示。同时这篇文章将作为后续文章的引子，在此之后，我将通过两篇文章通过具体实例的形式讲述如果在项目将T4为我所用，以达到提高开发效率和保证质量的目的。[这里有T4相关的资料][文中的例子可以从这里下载]

目录
一、我们的目标是：从XML文件到C#代码
二、从Hello World讲起
三、T4模板的基本结构
四、通过T4模板实现从“数据到代码”的转变
五、T4的文本转化的实现

一、我们的目标是：从XML文件到C#代码

再次重申一下我们需要通过“代码生成”需要达到的目的。无论对于怎么样的应用，我们都需要维护一系列的消息。消息的类型很多，比如验证消息、确认消息、日志消息等。我们一般会将消息储存在一个文件或者数据库中进行维护，并提供一些API来获取相应的消息项。这些API一般都是基于消息的ID来获取的，换句话说，消息获取的方式是以一种“弱类型”的编程方式实现的。如果我们能够根据消息存储的内容动态地生成相应的C#或者VB.NET代码，那么我们就能够以一种强类型的方式来获取相应的消息项了。

比如说，现在我们定义了如下一个MessageEntry类型来表示一个消息条目。为了简单，我们尽量简化MessageEntry的定义，仅仅保留三个属性Id、Value和Category。Category表示该消息条目所属的类型，你可以根据具体的需要对其分类（比如根据模块名称或者Severity等）。Value是一个消息真实的内容，可以包含一些占位符（{0}，{1},…{N}）。通过指定占位符对用的值，最中格式化后的文本通过Format返回。

   1: public class MessageEntry

   2: {

   3:     public string Id { get; private set; }

   4:     public string Value { get; private set; }

   5:     public string Category { get; private set; }

   6:  

   7:     public MessageEntry(string id, string value, string category)

   8:     {

   9:         this.Id         = id;

  10:         this.Value      = value;

  11:         this.Category   = category;

  12:     }

  13:     public string Format(params object[] args)

  14:     {

  15:         return string.Format(this.Value, args);

  16:     }

  17: }

现在我们所有的消息定义在如下一个XML文件中，<message>XML元素代码一个具体的MessageEntry，相应的属性（Attribute）和MessageEntry的属性（Property）相对应。

   1: <?xml version="1.0" encoding="utf-8" ?>

   2: <messages> 

   3:   <message id="MandatoryField" value="The {0} is mandatory."  category="Validation"/> 

   4:   <message id="GreaterThan" value="The {0} must be greater than {1}."  category="Validation"/> 

   5:   <message id="ReallyDelete" value="Do you really want to delete the {0}."  category="Confirmation"/>  

   6: </messages>

在上面的XML中，定义了两个类别（Validation和Confirmation）的三条MessageEntry。我们需要通过我们的代码生成工具生成一个包含如下C#代码的CS文件。

   1: public static class Messages

   2: {

   3:     public static class Validation

   4:     {

   5:         public static MessageEntry MandatoryField = new MessageEntry("MandatoryField", "The {0} is mandatory.", "Validation");

   6:         public static MessageEntry GreaterThan = new MessageEntry("GreaterThan", "The {0} must be greater than {1}.", "Validation");

   7:     }

   8:     public static class Confirmation

   9:     {

  10:         public static MessageEntry ReallyDelete = new MessageEntry("ReallyDelete", "Do you really want to delete the {0}.", "Confirmation");

  11:     }

  12: }

那么如何通过T4的方式来实现从“数据”（XML）到“代码”的转换呢？在投入到这个稍微复杂的工作之前，我们先来弄个简单的。

二、从Hello World讲起

我们之前一直在讲T4，可能还有人不知道T4到底代表什么。T4是对“Text Template Transformation Toolkit”（4个T）的简称。T4直接包含在VS2008和VS2010中，是一个基于文本文件转换的工具包。T4的核心是一个基于“文本模板”的转换引擎（以下简称T4引擎），我们可以通过它生成一切类型的文本型文件，比如我们常用的代码文件类型包括：C#、VB.NET、T-SQL、XML甚至是配置文件等。

对于需要通过T4来进行代码生成工作的我们来说，需要做的仅仅是根据转换源（Transformation Source），比如数据表、XML等（由于例子简单，HelloWord模板没有输入源）和目标文本（比如最终需要的C#或者T-SQL代码等）定义相应的模板。T4模板作用就相当于进行XML转化过程中使用的XSLT。

T4模板的定义非常简单，整个模板的内容包括两种形式：静态形式和动态动态。前者就是直接写在模板中作为原样输出的文本，后者是基于某种语言编写代码，T4引擎会动态执行它们。这和我们通过内联的方式编写的ASP.NET页面很相似：HTML是静态的，以C#或者VB.NET代码便写的动态执行的代码通过相应的标签内嵌其中。为了让读者对T4模板有一个直观的认识，我们先来尝试写一个最简单的。假设我们需要通过代码生成的方式生成如下一段简单的C#代码：

   1: using System;

   2:  

   3: namespace Artech.CodeGeneration

   4: {

   5:     class Program

   6:     {

   7:         static void Main(string[] args)

   8:         {

   9:             Console.WriteLine("Hello, {0}", "Foo");

  10:             Console.WriteLine("Hello, {0}", "Bar");

  11:             Console.WriteLine("Hello, {0}", "Baz");

  12:         }

  13:     }

  14: }

现在我们直接通过VS来创建一个T4模板来生成我们期望的C#代码。右击项目文件，选择"Add"|"New Item",在模板列表中选择"Text Template"。指定文件名后确定，一个后缀名为.tt的文件会被创建，然后在该文件中编写如下的代码。

   1: <#@ template debug="false" hostspecific="false" language="C#" #>

   2: <#@ assembly name="System.Core.dll" #>

   3: <#@ import namespace="System" #>

   4: <#@ output extension=".cs" #>

   5: using System;

   6:  

   7: namespace Artech.CodeGeneration

   8: {

   9:     class Program

  10:     {     

  11:         static void Main(string[] args)

  12:         {    

  13:             <#

  14:             foreach(var person in this.InitializePersonList()) 

  15:             {

  16:             #>

  17:                 Console.WriteLine("Hello, {0}","<#=  person#>");

  18:             <#

  19:             } 

  20:             #>

  21:         }

  22:     }

  23: }

  24:  

  25: <#+ 

  26:     public string[] InitializePersonList()

  27:     {

  28:         return new string[]{"Foo","Bar","Baz"};

  29:     }

  30: #>

保存该文件后，一个.cs文件将会作为该TT文件的附属文件被添加（如右图所示的HelloWorld.cs）。上述的这个TT文件虽然简单，却包含了构成一个T4模板的基本元素。在解读该T4模板之前，我们有必要先来了解一个完整的T4模板是如何构成的。

三、T4模板的基本结构

假设我们用“块”（Block）来表示构成T4模板的基本单元，它们基本上可以分成5类：指令块（Directive Block）、文本块（Text Block）、代码语句块（Statement Block）、表达式块（Expression Block）和类特性块（Class Feature Block）。

1、指令块（Directive Block）

和ASP.NET页面的指令一样，它们出现在文件头，通过<#@…#>表示。其中<#@ template …#>指令是必须的，用于定义模板的基本属性，比如编程语言、基于的文化、是否支持调式等等。比较常用的指令还包括用于程序集引用的<#@ assembly…#>，用于导入命名空间的<#@ import…#>等等。

2、文本块（Text Block）

文本块就是直接原样输出的静态文本，不需要添加任何的标签。在上面的模板文件中，处理定义在<#… #>、<#+… #>和<#=… #>中的文本都属于文本块。比如在指令块结束到第一个“<#”标签之间的内容就是一段静态的文本块。

   1: using System;

   2:  

   3: namespace Artech.CodeGeneration

   4: {

   5:     class Program

   6:     {     

   7:         static void Main(string[] args)

   8:         {    

   9:             

3、代码语句块（Statement Block）

代码语句块通过<#Statement#>的形式表示，中间是一段通过相应编程语言编写的程序调用，我们可以通过代码语句快控制文本转化的流程。在上面的代码中，我们通过代码语句块实现对一个数组进行遍历，输出重复的Console.WriteLine(“Hello, {0}”, “Xxx”)语句。

   1: <#

   2: foreach(var person in this.InitializePersonList()) 

   3: {

   4: #>

   5:     Console.Write("Hello, {0}","<#=  person#>");

   6: <#

   7: } 

   8: #>

4、表达式块（Expression Block）

表达式块以<#=Expression#>的形式表示，通过它之际上动态的解析的字符串表达内嵌到输出的文本中。比如在上面的foreach循环中，每次迭代输出的人名就是通过表达式块的形式定义的（<#=  person#>）

5、类特性块（Class Feature Block）

如果文本转化需要一些比较复杂的逻辑，我们需要写在一个单独的辅助方法中，甚至是定义一些单独的类，我们就是将它们定义在类特性块中。类特性块的表现形式为<#+ FeatureCode #>，对于Hello World模板，得到人名列表的InitializePersonList方法就定义在类特性块中。

   1: <#+ 

   2:     public string[] InitializePersonList()

   3:     {

   4:         return new string[]{"Foo","Bar","Baz"};

   5:     }

   6: #>

了解T4模板的“五大块”之后，相信读者对定义在HelloWord.tt中的模板体现的文本转化逻辑应该和清楚了吧。

四、通过T4模板实现从“数据到代码”的转变

现在我们来完成我们开篇布置得任务：如何将一个已知结构的表示消息列表的XML转换成C#代码，使得我们可以一强类型的编程方式获取和格式化相应的消息条目。我们的T4模板定义如下

   1: <#@ template debug="false" hostspecific="true" language="C#" #>

   2: <#@ assembly name="System.Core.dll" #>

   3: <#@ assembly name="System.Xml" #>

   4: <#@ import namespace="System" #>

   5: <#@ import namespace="System.Xml" #>

   6: <#@ import namespace="System.Linq" #>

   7: <#@ output extension=".cs" #>

   8:  

   9: namespace MessageCodeGenrator

  10: {

  11:     public static class Messages

  12:     {    

  13:         <# 

  14:         XmlDocument messageDoc = new XmlDocument();

  15:         messageDoc.Load(this.Host.ResolvePath("Messages.xml"));

  16:       

  17:         var messageEntries = messageDoc.GetElementsByTagName("message").Cast<XmlElement>();  

  18:         var categories = (from element in messageEntries

  19:                             select element.Attributes["category"].Value).Distinct();

  20:         foreach (var category in categories)  

  21:         {

  22:             #>

  23: public  static class <#=  category#>

  24:             {

  25:                 <#

  26:                 foreach (var element in messageDoc.GetElementsByTagName("message").Cast<XmlElement>().Where(element => element.Attributes["category"].Value == category))  

  27:                 {                      

  28:                     string id           = element.Attributes["id"].Value;  

  29:                     string value        = element.Attributes["value"].Value;  

  30:                     string categotry    = element.Attributes["category"].Value;

  31:                 #>

  32: public static MessageEntry <#= id #> = new MessageEntry("<#= id #>","<#=  value#>","<#=  categotry#>");

  33:             <#  } #>

  34:             }

  35:     <# } #>

  36:     }

  37: }

模板体现出来的转化流程就是：加载XML文件（Messages.xml），然后获取所有的消息类别，为每个消息类别创建一个内嵌于静态类Messages中的以类别命名的类。然后遍历每个类别下的所有消息条目，定义类型为MessageEntry的静态熟悉。

在这里有一点需要特别指出的是：整个代码生成的输入，即XML文件Messages.xml和模板文件位于相同的目录下，但是我们需要通过Host属性的ResolvePath方法去解析文件的物理路径。对ResolvePath方法的调用，需要模板<#@ template …#>指令中的hostspecific设置为true。

   1: <#@ template debug="false" hostspecific="true" language="C#" #>

五、T4的文本转化的实现

和我之前采用的代码生成方式（CodeDOM+Custom Tool）一样，对于T4模板的代码生成，VS最终还是通过Custom Tool来完成的。如果你查看TT文件的属性，你会发现Custom Tool会自动设置成：TextTemplatingFileGenerator。

当TextTemplatingFileGenerator被触发后（修改后的文件被保存，或者认为执行Custom Tool），会通过T4引擎完成文本的转换和输出工作。具体来讲，T4引擎的文本转化和输出机制可以通过下图来表示。T4引擎首先对模板的静态内容和动态内容进行解析，最终生成一个继承自Microsoft.VisualStudio.TextTemplating.TextTransformation的类，所有的文本转化逻辑被放入被重写的Transformation方法中。然后动态创建该对象，执行该方法并将最终的类型以附加文件的形式输出来。