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