2017年9月11日 星期一

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

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

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

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

TemplateBuilder的一些特殊檔案

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

  1. _Definition\_project.vstemplate.xml
  2. _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用於CSharpVB,那麼就會保留CSharp.vstemplateVB.vstemplate

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

image
image
建立item template和建立出來的內容

_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和複製檔案到資料夾裡面。
image
image
建立結構
在VS裡面加入相關檔案和csproj
VS加入相關檔案。
image
加入相關
測試

這邊template名稱有改成Convention Template比較容易看

image
測試VS

如果需要修改template,可以用另外一個VS來開啟對應的sln或者csproj,然後在那邊直接像一般開發的方式來調整template,確認好了之後,在切回到vsix專案直接build,template就更新了。

結語

整個TemplateBuilder的精髓就在一些Convention和一些特殊檔案讓建立tempalte變得簡單。

雖然沒有介紹Item Template的做法,但是基本概念一樣。

到目前為止,TemplateBuilder快到一個段落了,不過還有一種複雜template還沒介紹,也就是Multi Project Template。

因此,下一篇將會介紹Multi Project Template。


沒有留言 :

張貼留言