2017年8月27日 星期日

[打造自己的template-建立一致性程式碼][04]了解vstemplate來微調匯出的Template和強制VS更新Template的方式

解vstemplate來微調匯出的Template和強制VS更新Template的方式
了解vstemplate來微調匯出的Template和強制VS更新Template的方式

在上一篇[打造自己的template-建立一致性程式碼][03]透過匯出建立Project Template透過匯出的方式得到了 一個zip檔案。可以透過放到對應位置來達到安裝到VS上面。

但是匯出來的zip檔案其實有一些不如意的地方,因此在這篇將會介紹Project Template組成的原理來方便微調並且介紹如何讓VS更新Template。

之前建立的sample 程式用來產生範本在 github mhat-visualstudio-template sample/chapter02

了解匯出的zip檔案內容

首先,先來了解一下Visual Studio (以下簡稱VS) 匯出的zip檔案包含了什麼內容。

如果我們把它解壓縮出來,會發現整個資料夾內容和我們專案差不多,我們專案有的內容,zip裡面也有,不過zip版本有幾個不同的地方:

  1. 多了一個 MyTemplate.vstemplate 的檔案
  2. *.cs檔案有被調整過
zip檔案內容
zip檔案內容

vstemplate檔案內容

*.vstemplate基本上定義了Project Template的相關資訊和Project Template建立的時候那些檔案要被建立出來。

這個xml的根節點是VSTemplate,這個根節點會定義這次的Template是那種,以我們的例子是 Type="Project"表示是Project Template

VSTemplate裡面有有幾個部分:

TemplateData
專案的一些meta資訊
TemplateConten
定義有哪些檔案要包含在Project Template裡面
WizardExtension
這個我們匯出的Project Template沒有,但是如果未來在Project Template建立的過程有特殊邏輯要處理,可以寫C#程式達到客制目的。哪些就會定義在這邊
WizardData
可以傳入到WizardExtensio的參數
更多介紹,可以參考:VSTemplate Element (Visual Studio Templates)

整個vstemplate看起來如下:


  
    MHAT.Console.ProcessTemplate.ExecuteWithOption
    MHAT ConsoleApp ProcessTemplate 讀取參數一次性執行的Echo程式碼範例
    CSharp
    
    
    1000
    true
    MHAT.Console.ProcessTemplate.ExecuteWithOption
    true
    Enabled
    true
    __TemplateIcon.ico
  
  
    
      App.config
      
        EchoProcessOption.cs
      
      packages.config
      
        EchoProcess.cs
      
      Program.cs
      
        AssemblyInfo.cs
      
    
  

TemplateData

這裡面放的是一些Project Template的meta資訊,其中有幾個比較會調整的有:

name
這個是在VS裡面顯示的名稱。
description
選中某個Project Template之後右邊呈現的訊息
ProjectType
顯示在那個大分類下面,CSharp就是顯示在Visual C#
defaultname
當選中Project Template的時候,預設要顯示的專案名稱
NumberOfParentCategoriesToRollUp
這個在我們的檔案沒有,不過意思是多少以上也能夠顯示這個Project Template。等一下會提到分類這個事情,如何在上層分類也顯示下層分類的Project Template就是靠這個參數值。
更多關於每個參數的用途,可以參考 TemplateData Element (Visual Studio Templates)

TemplateConten

這邊定義的是Project Template建立的時候,那些檔案會建立出來,基本上看名稱應該可以猜的出來做什麼的,不過有幾個要提一下:

targetfilename
這個定義建立出來的時候這個檔案的名稱要是什麼。舉例來說,有可能建立的檔案前面的部分要用使用者輸入的名稱 - 就是改這個attribute
replaceparameters
如果建立出來的檔案有部分內容要和使用者建立時候輸入的檔案名稱對應 - 那麼就會用到特殊的Parameter,這個參數表示這個檔案是否要做Parameter替換處理。
更多關於每個參數的作用,可以參考:TemplateContent Element (Visual Studio Templates)

cs檔案有被調整的內容 - Parameter介紹

如果我們打開一個cs檔案,例如Program.cs,會注意到,有些值被改成了用錢字號包起來$safeprojectname$

這些其實是表示會被替換的Parameter,還記得上面有提到一個在vstemplate裡面,replaceparameters的attribute,那個值決定檔案裡面的Parameter是否要被替換。

因為有了這些,我們才能夠在新增的時候,namespace會和輸入的專案名稱有關。

這個Parameter可以用在vstemplate裡面的targetfilename,讓檔名可以和輸入的專案名稱呼應。
有哪些可用的Parameter可以再這裡:Template Parameters找到資訊。

微調的部分

上面介紹了Project Template的組成,有了這些資訊,有些地方我們可以做一些微調,分別為:

  1. 修正建立專案預設名稱
  2. 管理Project Template到某個分類

修正建立專案預設名稱

在我們匯出的時候,讓我們輸入Template Name的值會用作於選擇專案時候的名稱預設專案名稱

可是一般來說這兩個值可能不同,舉例來說,建立一個C# console,他的Template名稱是:Console App (.Net Framework),但是預設專案名稱則是:ConsoleApp

因此建議調整name(template名稱)和defaultname(專案預設名稱)

管理Project Template到某個分類

我們上篇Project Template出現的地方在Visual C#,如果未來我們這個專案有很多template,Visual C#這個節點會越積越多,造成不好查找。

因此如果可以把相關template放在一起,到時候查找相關就很方便。

建立分類很方便,只需要建立資料夾層級然後把template zip丟進去就好了。

舉例來說,如果我這個template想要放在 MHAT -> ConsoleAppProcessTemplate下面,那麼我就會把template放到對應資料夾位置。

放到正確結構
在new project template可以看到分類正確
放到正確結構,在new project template可以看到分類正確
分類只能歸在某個語言下面,例如Visual C#,無法建立 Visual C#那個層級
還記得上面提到NumberOfParentCategoriesToRollUp,目前沒有設,所以當我們選到MHAT這個分類的時候,會看不到東西,如果有設定值為1,表示上面1層也看得到這個template。

更新template - 如何讓vs重新刷新

假設今天要更新template - 不管是改了vstemplate檔案,還是重新調整之後匯出zip檔案,丟到了對應的位置,很有可能開啟new project還是沒有發現template或者template建立了沒有更新的內容。

因此這邊有個小tips可以確保template都會更新成功。

在系統裡面,有個地方是放VS template zip解壓縮內容的地方,我們只要把那邊刪掉,重啟VS就會重新從zip裡面解壓縮出來,達到更新成功的目的。

操作步奏如下:

  1. 找到對應的VS 暫存位置
  2. 把ProjectTemplates的部分刪掉
  3. 重新開啟VS

找到對應的VS 暫存位置

直接在檔案總管輸入:%appdata%\Microsoft\VisualStudio\

找到你的 {VS版本}_{後面幾個奇怪數字}的資料夾,舉例來說在我電腦15.0_00cdbf3e是我的VS 2017的暫存位置

如果今天是VS的Experimental Instance(後面提到用VSIX建立template會用到),那麼規則變成 {VS版本}_{後面幾個奇怪數字}Exp,舉例來說15.0_00cdbf3eExp

把對應的TemplateCache資料夾刪掉

舉例來說,今天如果是要重設Project Template,就是把ProjectTemplatesCache資料夾刪掉。如果是Item Template(下一篇提到),則是把ItemTemplatesCache砍掉。

要刪掉的ProjectTemplateCache資料夾
要刪掉的ProjectTemplateCache資料夾

重新開啟VS

不需要把現在有開的VS關掉,直接開一個新的,然後Project Template就會更新 - ProjectTemplateCache也會自動被建立出來。

結語

在這篇深入了解了匯出的template內容,了解了vstemplate的幾個重要欄位和設定,最後還了解了如何確保VS更新template。

對於單個Project Template的建立也算告一個段落。

在下篇,將會介紹如何建立Multi Project Template(建立出來的時候有2個project)。  

 

沒有留言 :

張貼留言

您或許對這些文章有興趣: