[打造自己的template-建立一致性程式碼][11]深入了解TemplateBuilder的特殊檔案設定方式＠ Alan Tsai 的學習筆記

[打造自己的template-建立一致性程式碼][11]深入了解TemplateBuilder的特殊檔案設定方式

圖片來源：https://pixabay.com/en/annual-report-book-brochure-686343/

在上一篇（[10]用SideWaffle建立Project Template）了解了如何用SideWaffle建立出project的方式。

在這一篇將會更深入的介紹TemplateBuilder裡面的一些特殊檔案的作用和如何微調讓產生出想要的Template。

匯出用的範例程式碼 github mhat-visualstudio-template sample/chapter11

TemplateBuilder的一些特殊檔案

_Definition\_project.vstemplate.xml

和*.vstemplate~的差異

_preprocess.xml

TemplateBuilder的Convention
結語

TemplateBuilder的一些特殊檔案

還記得其實建立Template的背後功臣是TemplateBuilder，而TemplateBuilder透過一些特殊的檔案和習慣（Convention）來讓建立template變得簡單：

_Definition\_project.vstemplate.xml
_preprocess.xml

_Definition\_project.vstemplate.xml

在上篇的Add Template Reference其中被加入的一個檔案就是_Definition\_project.vstemplate.xml。

這個檔案打開來看會發現和一般定義template用到的vstemplate基本一樣，唯一差異的地方是：

Project的內容完全沒有（主要用來定義template要包含什麼內容）。

這其實就是TemplateBuilder好的地方，template要包含的內容，會由csproj有包含的內容整合到_project.vstemplate.xml檔案裡面。

這也是為什麼如果有改template，就像一般開發，然後直接build就好 - 原因就在於TemplateBuilder會在build的時候把csproj和_project.vstemplate.xml結合。

和*.vstemplate~的差異

在SideWaffle裡面有一個Item Template叫做SideWaffle Definition Folder，會建立Definitions資料夾，然後裡面有好幾個以*.vstemplate~的檔案

這種和_project.vstemplate.xml差異在於，_project.vstemplate.xml會結合csproj的檔案，而*.vstemplate~則不會，他們的作用則是快速建立不同語言的template。舉例來說，今天要建立一個template用於CSharp和VB，那麼就會保留CSharp.vstemplate和VB.vstemplate

(這邊注意要把尾巴的~拿掉才有作用)

_preprocess.xml

這個檔案有兩個目的：

設定關鍵字替換

上面的_project.vstemplate.xml讓我們不用自己手動設定說那些檔案要包含在template裡面，完全看csproj有包含的檔案。

但是這樣建立出來還有個問題就是，有些內容希望替換掉，例如namespace要改成使用者建立時候輸入的內容，這個就是這個檔案的作用。

以下面的範例為例：

<Replacements Include="*.*" Exclude="*.vstemplate;*.csproj;*.fsproj;*.vbproj;*.jpg;*.png;*.ico;_preprocess.xml;_project.vstemplate.xml">
 <add key="MHAT.ConsoleWithOption" value="$safeprojectname$"/>
</Replacements>

Replacements可以設定那些檔案要包含，然後那些檔案要略過，然後每一個關鍵字就是用add來加。

以這邊例子就是把目前namespace改成建立時候給的名稱。

可以看到，要被替換的內容可以用Parameter

設定template的分類

會希望建立的template在某些template的分類裡面，這個就是_preprocess.xml裡面的：

     <TemplateInfo Path="CSharp\Web\SideWaffle"/>

以上就是設定template要放在C#->Web->SideWaffle裡面

_preprocess.xml是可以多個，離檔案越近的_preprocess.xml權重越高，可以透過這種方式來針對某些資料夾特殊處理。

TemplateBuilder的Convention

TemplateBuilder其實有特殊Convention的資料夾，分別為：

ProjectTemplates
ItemTemplates
Snippet

只要建立資料夾把檔案放到對應的資料夾，就會建立出對應的template/Snippet。所以除了上篇提到的Add Template Reference，其實也可以用這種方式來建立。

以昨天的例子來說：

建立出Convention的資料夾結構和複製檔案: 基本上就是ProjectTemplates -> ConsoleWithOption和複製檔案到資料夾裡面。; 建立結構
在VS裡面加入相關檔案和csproj: VS加入相關檔案。

加入相關
測試: 這邊template名稱有改成Convention Template比較容易看

測試VS