自訂 dotnet new 專案範本的重要觀念與範例 | The Will Will Web

The Will Will Web

記載著 Will 在網路世界的學習心得與技術分享

自訂 dotnet new 專案範本的重要觀念與範例

.NET Core 內建的範本功能簡單好上手,由於架構簡化許多 (相較於 Visual Studio 範本),所以也非常好上手。在仔細研究之後,發現還是蠻多小細節的,只要事先建立一些重要的基本觀念,要寫出好用、實用的專案範本一點都不麻煩。

範本基本概念

  • 列出目前所有範本

    透過 -l 參數可以列出目前所有已安裝的專案範本清單:

    dotnet new -l
    

    透過 -u 參數則會列出目前所有範本的詳細資訊:

    dotnet new -u
    

    雖然加上 -u 參數是用來移除現有範本之用,但是 -u 不加上參數時,卻可以列出目前所有範本的詳細資訊,你可以看見每個範本的 NuGetPackageIdVersion 版本號,還能得知移除範本所需的命令!

  • 範本的種類

    在 Visual Studio 裡面,範本有兩種:

    1. 專案範本 (Project Templates)
    2. 項目範本 (Item Templates)

    在使用 .NET Core CLI 的時候,你可以搭配 --type 參數來篩選範本,例如:

    dotnet new -l --type=project
    dotnet new -l --type=item
    dotnet new -l --type=other
    

    預設 --type 參數只有三種可能的值:projectitemother

範本的組成項目

範本的組成包含兩種成分:

  1. 來源檔案和資料夾

    也就是所有要被自動產生的檔案資料夾,基本上不限定任何檔案型態或格式,任何檔案都可以當成範本的一部分。

  2. 設定檔 (template.json)

    你必須建立一個 .template.config/template.json 設定檔,用來告訴 .NET Core CLI 該怎樣產生新檔案。其內容範例如下:

    {
        "$schema": "http://json.schemastore.org/template",
        "identity": "Duotify.WebAPI.3.1",
        "author": "Will Huang",
        "classifications": [ "Common", "Code" ],
        "name": "Example templates: string extensions",
        "shortName": "duotify-webapi",
        "tags": {
            "language": "C#",
            "type": "project"
        },
        "sourceName": "MyProject.Con",
        "preferNameDirectory": true
    }
    

    上述這些 Properties (屬性) 除了 tags 以外,都是必要的屬性,分別說明如下:

    • $schema: 此為 template.json 檔案的 JSON 結構描述 URI,只要設定上去,編輯器就會開始提供 IntelliSense 自動完成能力。

      image

    • identity: 此範本的唯一名稱,不能跟任何其他範本重複。

    • name: 使用者在執行 dotnet new -l 時會看到的範本名稱

    • shortName: 執行 dotnet new shortName 命令時所使用的範本短名

    • author: 宣告範本的作者名稱

    • classifications: 範本分類 (字串陣列)。當你執行 dotnet new -l 列出範本清單時,會自動出現在「標記」(Tags) 欄位中。

    • tags: 用來宣告範本的標記資訊,從名稱來看,很容易跟 classifications 混淆,因為都是「標記」的意思。這個屬性主要用來跟 dotnet new--type--lang 兩個參數搭配使用。tags 屬性下包含兩個子屬性:

      • language: 程式語言。可能的值有:C#VBF#,除此之外你也可以設定為任何語言。
      • type: 範本類型。這裡只有兩種可能的值:project (專案範本)、item (項目範本)。你也可以指定任意字串。
    • sourceName: 指定來源名稱

      • 我們在執行 dotnet new 的時候,可以指定 -n 參數,這個參數定義了專案名稱
      • 這裡所定義的 sourceName 其實是一個可以被取代的變數,如果你設定為 MyProject.Con 的話,當你在執行 dotnet new 的時候,程式會自動找出來源檔案和資料夾中所有檔案/目錄名稱檔案內容,並將 MyProject.Con 字串替換成 -n 參數指定的名稱字串。
    • preferNameDirectory: 在執行 dotnet new 的時候,如果你有指定 -n 參數,預設會建立一個與 -n 參數值同名的資料夾,如果你將該屬性設定為 false 的話,就不會建立額外的資料夾。此屬性預設為 true

群組識別與標記

如果你定義了 groupIdentity 屬性,會將多個範本合併成一個顯示項目,執行 dotnet new 的時候,就必須搭配 --type--lang 參數來選擇要執行的範本。這個時候範本中的 tags 屬性就一定要設定了,該屬性下的 languagetype 就是用來給這兩個參數篩選用的。

dotnet new mysample --type=item -lang=C#
dotnet new mysample --type=project -lang=C#

練習建立專案範本

請參考以下文件建立 項目範本專案範本範本套件

  1. 教學課程:建立項目範本
  2. 教學課程:建立專案範本
  3. 教學課程:建立範本套件

如果想參考其他人所寫的範本,可以參考以下網址:

相關連結