The Will Will Web

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

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

📅 2020/01/19 17:10 📁 .NET Core

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

範本基本概念

  • 列出目前所有範本

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

    dotnet new -l

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

    dotnet new -u

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

  • 範本的種類

    在 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 參數只有三種可能的值：project、item 與 other。

範本的組成項目

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

  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#、VB、F#，除此之外你也可以設定為任何語言。
      • 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 屬性就一定要設定了，該屬性下的 language 與 type 就是用來給這兩個參數篩選用的。

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

練習建立專案範本

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

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

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

相關連結

留言評論