教學課程：建立專案範本

  • 發行項

您可以使用 .NET 建立及部署範本，以產生專案、檔案，甚至是資源。 此教學課程是指導您如何建立、安裝及解除安裝能搭配 dotnet new 命令使用之範的本系列文章第二部分。

提示

在下列存放庫中可找到 .NET SDK 隨附的官方 .NET 範本：

範本 存放庫
主控台、類別庫和一般項目範本 dotnet/sdk
ASP.NET 和 Blazor 範本 dotnet/aspnetcore
ASP.NET 單頁應用程式範本 dotnet/spa-templates
WPF 範本 dotnet/wpf
Windows Forms 範本 dotnet/winforms
測試範本 dotnet/test-templates
MAUI 範本 dotnet/maui

您可執行 dotnet new list 命令來檢視電腦上安裝的範本。

在這部分的系列文章中，您將了解如何：

  • 建立專案範本的資源。
  • 建立範本設定資料夾和檔案。
  • 從檔案路徑安裝範本。
  • 測試項目範本。
  • 將項目範本解除安裝。

必要條件

  • 完成此教學課程系列的第 1 部分。
  • 開啟終端並瀏覽至 working\content 資料夾。

重要

本文是針對 .NET 7 撰寫的。 不過，其也適用於 .NET 6 和舊版，但有一個差異：語法 dotnet new 不同。 list、search、install 和 uninstall 子命令分別應為 --list、--search、--install 和 --uninstall 選項。

例如，.NET 7 中的 dotnet new install 命令會在 .NET 6 中變成 dotnet new --install。 您可以使用 dotnet new --help 命令來查看所有選項漢子命令的清單。

建立專案範本

專案範本能產生可立即執行的專案，讓使用者能以一組已可運作的程式碼來輕鬆開始。 .NET 包含幾個專案範本，例如主控台應用程式或類別庫。 在此範例中，您會建立新的主控台應用程式專案，以標準的「Hello World」主控台輸出取代非同步執行的輸出。

在您的終端機中，瀏覽至 working\content 資料夾，並建立名為 consoleasync 的新子資料夾。 進入該子資料夾，然後執行 dotnet new console 以產生標準主控台應用程式。 您將會編輯由此範本所產生的檔案來建立新的範本。

working
└───content
    └───consoleasync
            consoleasync.csproj
            Program.cs

修改 Program.cs

開啟 Program.cs 檔案。 標準主控台專案不會以非同步方式寫入主控台輸出，現在讓我們來新增專案。 將該程式碼變更為下列程式碼，並儲存檔案：

// See https://aka.ms/new-console-template for more information
await Console.Out.WriteAsync("Hello World with C#");

您已經建立範本的內容，現在您需要在範本的根資料夾建立範本設定。

建立範本設定

在此教學課程中，您的範本資料夾是位於 working\content\consoleasync。

.NET 可辨識範本，因為其在範本資料夾根目錄下具有特殊的資料夾和組態檔。

首先，建立名為 .template.config 的新子資料夾，然後進入它。 然後，建立名為 template.json 的新檔案。 您的資料夾結構看起來應該像這樣：

working
└───content
    └───consoleasync
        └───.template.config
                template.json

使用您慣用的文字編輯器開啟 template.json，然後貼上下列 json 程式碼並儲存。

{
  "$schema": "http://json.schemastore.org/template",
  "author": "Me",
  "classifications": [ "Common", "Console" ],
  "identity": "ExampleTemplate.AsyncProject",
  "name": "Example templates: async project",
  "shortName": "consoleasync",
  "sourceName":"consoleasync",
  "tags": {
    "language": "C#",
    "type": "project"
  }
}

此設定檔會包含您範本的所有設定。 您可以看見基本設定 (例如 name 和 shortName)，但還有設定為 project 的 tags/type 值。 這會將您的範本分類為「專案」範本。 您可以建立的範本類型本身並無限制。 item 和 project 值是 .NET 建議的常用名稱，以便讓使用者輕鬆篩選要搜尋的範本類型。

sourceName 項目是使用者使用範本時所取代的項目。 組態檔中 sourceName 的值會在每個檔案名稱和檔案內容中進行搜尋，且預設取代為目前資料夾的名稱。 當使用 dotnet new 命令傳遞 -n 或 --name 參數時，會使用所提供的值，而不是目前的資料夾名稱。 在此範本的案例中， consoleasync 會取代 .csproj 檔案的名稱。

classifications 項目代表您執行 dotnet new 並取得範本清單時所會看見的 [標籤] 欄。 使用者也可以根據分類標籤搜尋。 請勿混淆 template.json 檔案中的 tags 屬性與 classifications 標籤清單。 它們是兩個不同的概念，但不幸的是名稱相同。 template.json 檔案的完整結構描述位於 JSON 結構描述存放區 (英文)，並在 template.json 參考 (英文) 中進行了描述。 如需 template.json 檔案的詳細資訊，請參閱 dotnet 範本化 Wiki \(英文\)。

您已經具備有效的 .template.config/template.json 檔案，現在您的範本已經準備好並可供安裝。 在安裝範本前，請確定已刪除範本中不要包含的所有額外資料夾和檔案，例如 bin 或 obj 資料夾。 在您的終端機中，瀏覽至 consoleasync 資料夾，並執行 dotnet new install .\ 以安裝位於目前資料夾中的範本。 若使用 Linux 或 macOS 作業系統，請使用正斜線：dotnet new install ./。

dotnet new install .\

此命令會輸出已安裝範本的清單，其中應包含您的範本。

The following template packages will be installed:
   <root path>\working\content\consoleasync

Success: <root path>\working\content\consoleasync installed the following templates:
Templates                                         Short Name               Language          Tags
--------------------------------------------      -------------------      ------------      ----------------------
Example templates: async project                  consoleasync             [C#]              Common/Console

測試專案範本

現在您已安裝項目範本，請進行測試。

  1. 瀏覽至 test 資料夾。

  2. 使用下列命令建立新的主控台應用程式，以便產生工作專案，供您使用 dotnet run 命令輕鬆測試。

    dotnet new consoleasync -n MyProject

    您會獲得下列輸出。

    The template "Example templates: async project" was created successfully.

  3. 使用下列命令執行專案。

    dotnet run

    您會獲得下列輸出。

    Hello World with C#

恭喜！ 您已透過 .NET 建立並部署專案範本。 為了針對此教學課程系列的下一部份做準備，請將您所建立的範本解除安裝。 同時，請務必刪除 test 資料夾中的所有檔案。 這樣就能回到最原始的狀態，並準備好進行此教學課程系列的下一個部分。

解除安裝範本

在您的終端機中，瀏覽至 consoleasync 資料夾，並執行下列命令，以便將位於目前資料夾的範本解除安裝：

  • 在 Windows 上：dotnet new uninstall .\
  • 在 Linux 或 MacOS 上：dotnet new uninstall ./

此命令會輸出已解除安裝的範本清單，其中應包含您的範本。

Success: <root path>\working\content\consoleasync was uninstalled.

您可隨時使用 dotnet new uninstall 查看安裝的範本套件清單，每個範本套件皆包含該命令，以進行解除安裝。

下一步

在此教學課程中，您已建立專案範本。 若要了解如何將項目和專案範本封裝為易於使用的單一檔案，請繼續進行此教學課程系列。

建立範本套件