T4 Template Overview

T4 Template的组成

指令区:为模板转换引擎提供指令,控制模板如何被处理

• Ÿ   template：模板相关的属性，debug是否可以调试；hostspecific设置为true时，为生成的模板类中添加Host属性
• Ÿ   output：生成输出文件类型
• Ÿ   assembly：模板引擎中引用的程序集
• Ÿ   import：模板引擎中导入的命名空间
• Ÿ   include：包含其他文件，在最终转换时，将这些引用的文件和当前文件进行合并

代码控制区

• Ÿ   标准代码控制区，<#...#>包围的区域，包含标准的代码
• Ÿ   表达式控制区，<#=...#>包围的区域，计算表达式的值，插入到最终输出文件中
• Ÿ   类特性控制区，<#+...#>包围的区域，定义类、属性、方法等，主要用于帮助类或者帮助方法，可以其他代码区域引用这里定义的类和方法，该区域中包含的代码可以放在单独文件中，然后include到当前文件中

T4 工具方法

• Ÿ   Write，WriteLine：向模板中写入数据文本
• Ÿ   Error，在VS的Error Window面板显示错误
• Ÿ   Warning，在VS的Error Window面板显示警告

更多方法，请参考：http://msdn.microsoft.com/en-us/library/bb126474.aspx 

Host属性：引用模板转换引擎的宿主

• Ÿ   Microsoft.VisualStudio.TextTemplating.ITextTemplatingEngineHost类型
• Ÿ   使用Host.ResolvePath()引用相对于模板的路径
• Ÿ   使用Host.LogErrors打印错误信息，如果宿主是VS的话，就是向Error Window打印错误警告信息
• Ÿ   如果是在VS中使用，可以访问VS的API

建议的开发流程

• Ÿ   T4模板不是编写代码的理想环境(没有智能提示等)
• Ÿ   首先在其他工程中实现模板需要的功能
• Ÿ   将工程的代码迁移到T4模板中

Ÿ   如何Debug T4模板

• Ÿ   首先建议采用上面说的开发流程，T4模板的Debug是用来解决迁移过程中出现的问题
• Ÿ   template指令设置debug="true“
• Ÿ   添加断点
• Ÿ   在模板文件中右键Debug T4 Template

T4 Template的三个组件

引擎

如何生成GeneratedTextTransformation

GeneratedTextTransformation运行

使用自定义的TextTransformation

GeneratedTextTransformation继承自TextTransformation，如果要使用另外一套方法集，可以定义继承自TextTransformation的类，然后在template指令的inherits属性指定为该类

宿主

• Ÿ   加载引擎或者指令处理器需要的文本文件或者二进制文件，比如加载程序集、指令处理器代码文件，也可以读取文本文件，将它们的内容作为字符串返回
• Ÿ   为引擎创建GeneratedTextTransformation类提供一组标准的程序集和命名空间
• Ÿ   为引擎编译和执行GeneratedTextTransformation类提供AppDomain，使用独立的AppDomain是为保护宿主应用程序（VS）不受模板文件中错误的影响
• Ÿ   将生成的结果写入输出文件
• Ÿ   为生成的输出文件设置默认扩展名
• Ÿ   处理文件转换过程中出现的错误，比如写入文件中，又比如VS将错误显示到Error Window中
• Ÿ   为指令提供默认值,比如language默认值C#

自定义宿主

创建并运行自己的工程，引用Microsoft.VisualStudio.TextTemplating.11.0.dll和Microsoft.VisualStudio.TextTemplating.Interfaces.11.0.dll，主要是使用Engine的ProcessTemplate

更详细流程请参考官方文档：http://msdn.microsoft.com/en-us/library/bb126579.aspx

指令处理器

• Ÿ   提供公共功能,访问外部资源或数据
• Ÿ   引擎将指令转换为代码，添加到GeneratedTextTransformation中，比如Import指令最终添加为using代码语句

自定义指令处理器:

需要创建继承自DirectiveProcessor或者RequiresProvidesDirectiveProcessor的类，该类的重要接口如下

• Ÿ   bool IsDirectiveSupported(string directiveName)支持哪些指令，只有返回true的指令名称，才会进行下一步的处理
• Ÿ   void ProcessDirective (string directiveName, IDictionary<string, string> arguments)处理指令时，引擎调用这个方法，一般是将指令名称和参数保存下来为后面的操作做准备
• Ÿ   string[] GetReferencesForProcessingRun()返回模板需要的程序集名称
• Ÿ   string[] GetImportsForProcessingRun()返回模板需要的命名空间
• Ÿ   string GetClassCodeForProcessingRun()向GeneratedTextTransformation类中插入的实际代码，定义了公共功能如属性、方法等的代码

部署指令处理器

• Ÿ   Visual Studio Extension (VSIX)
• Ÿ   VSPackage
• Ÿ   注册表

详细部署流程，请参考官方文档：http://msdn.microsoft.com/en-us/library/cc138364.aspx

参考文档和资料

http://msdn.microsoft.com/en-us/library/bb126445.aspx

http://www.cnblogs.com/artech/archive/2010/11/16/T4_Assembly_Locking_Debug.html

http://www.cnblogs.com/artech/archive/2010/10/23/1859529.html

http://www.hanselman.com/blog/T4TextTemplateTransformationToolkitCodeGenerationBestKeptVisualStudioSecret.aspx