教學課程：建立範本套件

發行項
02/23/2024

您可以使用 .NET 建立及部署範本，以產生專案、檔案，甚至資源。本教學課程屬於系列文章的第三部分，將引導您建立、安裝及解除安裝可與 dotnet new 命令搭配使用的範本。

您可以在 .NET 範例 GitHub 存放庫中檢視已完成的範本。

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

使用 Microsoft.TemplateEngine.Authoring.Templates NuGet 套件建立範本套件。
從 NuGet 套件檔案安裝範本套件。
按套件識別碼解除安裝範本套件。

建立 *.csproj 專案以建置範本套件。
設定專案檔以用於封裝。
從 NuGet 套件檔案安裝範本套件。
按套件識別碼解除安裝範本套件。

必要條件

完成此教學課程系列的第 1 部分和第 2 部分。

此教學課程會使用在此教學課程系列的前兩個部分中所建立的兩個範本。您可以使用不同的範本，但前提是您必須將該範本以資料夾的形式複製到 working\content 資料夾中。
開啟終端並瀏覽至 working 資料夾。

安裝 .Net 8。
從 NuGet 套件摘要安裝 Microsoft.TemplateEngine.Authoring.Templates 範本。
- 從終端機執行 dotnet new install Microsoft.TemplateEngine.Authoring.Templates 命令。

重要

本文是針對 .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 命令來查看所有選項漢子命令的清單。

建立範本套專案

範本套件指的是其中封裝了一或多個範本的 NuGet 套件。當您安裝或解除安裝範本套件時，會相對應地新增或移除套件中所包含的所有範本。

範本套件會以 NuGet 套件 (.nupkg) 檔案來表示。此外，您可以將範本套件上傳至 NuGet 摘要，就像任何 NuGet 套件一樣。此 dotnet new install 命令支援從 NuGet 套件摘要、.nupkg 檔案或具有範本的目錄安裝範本套件。

通常，您可以使用 C# 專案檔來編譯程式碼並產生二進位檔。不過，專案也可以用來產生範本套件。透過變更 .csproj 的設定，您會防止它編譯任何程式碼，並改為使它將您範本的所有資產包含為資源。此專案建置後即會產生範本套件 NuGet 套件。

您即將產生的套件將包含 [item] 和 (cli-templates-create-item-template.md) 和先前建立的專案範本。

Microsoft.TemplateEngine.Authoring.Templates 套件包含製作範本很有用的範本。若要安裝此套件，nuget.org 應該在工作目錄中以 NuGet 摘要的形式提供。

在工作資料夾中，執行下列命令來建立範本套件：

dotnet new templatepack -n "AdatumCorporation.Utility.Templates"

-n 參數會將專案檔名稱設定為 AdatumCorporation.Utility.Templates.csproj。您應該會看到類似以下輸出的結果。

The template "Template Package" was created successfully.

Processing post-creation actions...
Description: Manual actions required
Manual instructions: Open *.csproj in the editor and complete the package metadata configuration. Copy the templates to _content_ folder. Fill in README.md.

接下來，在程式碼編輯器中開啟 AdatumCorporation.Utility.Templates.csproj 檔案，並根據範本中的提示填入：

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <!-- The package metadata. Fill in the properties marked as TODO below -->
    <!-- Follow the instructions on https://learn.microsoft.com/nuget/create-packages/package-authoring-best-practices -->
    <PackageId>AdatumCorporation.Utility.Templates</PackageId>
    <PackageVersion>1.0</PackageVersion>
    <Title>AdatumCorporation Templates</Title>
    <Authors>Me</Authors>
    <Description>Templates to use when creating an application for Adatum Corporation.</Description>
    <PackageTags>dotnet-new;templates;contoso</PackageTags>
    <PackageProjectUrl>https://your-url</PackageProjectUrl>

    <PackageType>Template</PackageType>
    <TargetFramework>net8.0</TargetFramework>
    <IncludeContentInPack>true</IncludeContentInPack>
    <IncludeBuildOutput>false</IncludeBuildOutput>
    <ContentTargetFolders>content</ContentTargetFolders>
    <NoWarn>$(NoWarn);NU5128</NoWarn>
    <NoDefaultExcludes>true</NoDefaultExcludes>
    ... cut for brevity ...

在工作資料夾中，執行下列命令來建立範本套件：

dotnet new console -n AdatumCorporation.Utility.Templates

-n 參數會將專案檔名稱設定為 AdatumCorporation.Utility.Templates.csproj。您應該會看到類似以下輸出的結果。

The template "Console Application" was created successfully.

Processing post-creation actions...
Running 'dotnet restore' on .\AdatumCorporation.Utility.Templates.csproj...
  Restore completed in 52.38 ms for C:\code\working\AdatumCorporation.Utility.Templates.csproj.

Restore succeeded.

刪除 Program.cs 檔案。新的專案範本會產生此檔案，但範本引擎不會使用。

接下來，在您慣用的編輯器中開啟 AdatumCorporation.Utility.Templates.csproj 檔案，並以下列 XML 取代其內容：

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <PackageId>AdatumCorporation.Utility.Templates</PackageId>
    <PackageVersion>1.0</PackageVersion>
    <Title>AdatumCorporation Templates</Title>
    <Authors>Me</Authors>
    <Description>Templates to use when creating an application for Adatum Corporation.</Description>
    <PackageTags>dotnet-new;templates;adatum</PackageTags>
    <PackageProjectUrl>https://your-url</PackageProjectUrl>

    <PackageType>Template</PackageType>
    <TargetFramework>netstandard2.0</TargetFramework>
    <IncludeContentInPack>true</IncludeContentInPack>
    <IncludeBuildOutput>false</IncludeBuildOutput>
    <ContentTargetFolders>content</ContentTargetFolders>
    <NoWarn>$(NoWarn);NU5128</NoWarn>
    <NoDefaultExcludes>true</NoDefaultExcludes>
  </PropertyGroup>

  <ItemGroup>
    <Content Include="content\**\*" Exclude="content\**\bin\**;content\**\obj\**" />
    <Compile Remove="**\*" />
  </ItemGroup>

</Project>

專案 XML 的描述

XML 程式碼片段中 <PropertyGroup> 底下的設定分成兩個群組。

第一個群組會處理 NuGet 套件的必要屬性。四個 <Package*> 設定和用來在 NuGet 摘要上識別您套件的 NuGet 套件屬性有關。 NuGet 所使用的 <PackageId> 值也會用來解除安裝範本套件。 <Title> 和 <PackageTags> 等其餘設定則都與顯示在 NuGet 摘要和 .NET 套件管理員上的中繼資料有關。如需 NuGet 設定的詳細資訊，請參閱 NuGet 和 MSBuild 屬性。

注意

若要確保範本套件出現在 dotnet new search 結果中，<PackageType> 必須設定為 Template。

在第二個群組中，<TargetFramework> 設定可確保當您在執行套件命令以編譯和封裝專案時，MSBuild 可正確執行。群組也包含與設置專案相關的設定，可在 NuGet 套件建立時將範本包含在適當的資料夾中：

<NoWarn> 設定可將不適用於範本套件專案的警告訊息隱藏。
<NoDefaultExcludes> 設定可確保以 . 開頭的檔案和資料夾 (例如 .gitignore) 會包含在範本中。 NuGet 套件的「預設」行為是忽略這些檔案和資料夾。

<ItemGroup> 包含兩個項目。首先，<Content> 項目包含 templates 資料夾中的一切，以作為內容。它也會排除任何 bin 資料夾或 obj 資料夾，以防止包含任何已編譯的程式碼 (如果您已測試並編譯您的範本的話)。接著，<Compile> 項目會將所有程式碼檔案從編譯中排除，無論這些檔案位於何處皆是如此。此設定可防止用於建立範本套件的專案嘗試編譯 templates 資料夾階層中的程式碼。

提示

如需 NuGet 中繼資料設定的詳細資訊，請參閱將範本封裝到 NuGet 套件 (nupkg 檔案)。

建立的專案檔包含範本製作 MSBuild 工作和當地語系化設定。

  <PropertyGroup>
    <LocalizeTemplates>false</LocalizeTemplates>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.TemplateEngine.Tasks" Version="*" PrivateAssets="all" IsImplicitlyDefined="true"/>
  </ItemGroup>

重要

content 內容資料夾包含 SampleTemplate 資料夾。刪除此資料夾，因為其已新增至製作範本以供示範之用。

這些 MSBuild 工作提供範本驗證和範本當地語系化的功能。預設會停用當地語系化。若要啟用當地語系化檔案的建立，請將 LocalizeTemplates 設定為 true。

封裝並安裝

儲存專案檔。在建置範本套件之前，請先確認您的資料夾結構正確無誤。您要封裝的任何範本都應置於 templates 資料夾中，也就是範本自己的資料夾。資料夾結構應於下列階層相似：

working
│   AdatumCorporation.Utility.Templates.csproj
└───content
    ├───extensions
    │   └───.template.config
    │           template.json
    └───consoleasync
        └───.template.config
                template.json

content 資料夾有兩個資料夾：extensions 和 consoleasync。

在終端中，從 working 資料夾執行 dotnet pack 命令。此命令會建置專案，並在 working\bin\Debug 資料夾中建立 NuGet 套件，如下列輸出所示：

MSBuild version 17.8.0-preview-23367-03+0ff2a83e9 for .NET
  Determining projects to restore...
  Restored C:\code\working\AdatumCorporation.Utility.Templates.csproj (in 1.16 sec).

  AdatumCorporation.Utility.Templates -> C:\code\working\bin\Release\net8.0\AdatumCorporation.Utility.Templates.dll
  Successfully created package 'C:\code\working\bin\Release\AdatumCorporation.Utility.Templates.1.0.0.nupkg'.

接下來，使用 dotnet new install 命令來安裝範本套件。在 Windows 上：

dotnet new install .\bin\Release\AdatumCorporation.Utility.Templates.1.0.0.nupkg

在 Linux 或 MacOS 上：

dotnet new install bin/Release/AdatumCorporation.Utility.Templates.1.0.0.nupkg

您應該會看到如下輸出：

The following template packages will be installed:
   C:\code\working\AdatumCorporation.Utility.Templates\bin\Release\AdatumCorporation.Utility.Templates.1.0.0.nupkg

Success: AdatumCorporation.Utility.Templates::1.0.0 installed the following templates:
Templates                                         Short Name               Language          Tags
--------------------------------------------      -------------------      ------------      ----------------------
Example templates: string extensions              stringext                [C#]              Common/Code
Example templates: async project                  consoleasync             [C#]              Common/Console/C#9

如果您將 NuGet 套件上傳至 NuGet 摘要，您可以使用 dotnet new install <PACKAGE_ID> 命令；其中 <PACKAGE_ID> 和 .csproj 檔案中的 <PackageId> 設定相同。

解除安裝範本套件

無論您是透過 .nupkg 檔案或透過 NuGet 摘要安裝範本套件，將其移除的方法都相同。使用您想要解除安裝之範本的 <PackageId>。您可以透過執行 dotnet new uninstall 命令來取得已安裝範本的清單。

C:\working> dotnet new uninstall
Currently installed items:
... cut to save space ...

  AdatumCorporation.Utility.Templates
    Details:
      NuGetPackageId: AdatumCorporation.Utility.Templates
      Version: 1.0.0
      Author: Me
    Templates:
      Example templates: async project (consoleasync) C#
      Example templates: string extensions (stringext) C#
    Uninstall Command:
      dotnet new uninstall AdatumCorporation.Utility.Templates

執行 dotnet new uninstall AdatumCorporation.Utility.Templates 解除安裝範本套件。命令會輸出解除安裝哪些範本套件的相關資訊。

恭喜！您已安裝並解除安裝範本套件。

下一步

若要深入了解範本 (您已經了解其大部分的內容)，請參閱 dotnet new 的自訂範本一文。

範本製作工具
dotnet/templating GitHub repo Wiki (維基百科：dotnet/templating GitHub 存放庫)
範本範例
JSON 結構描述保存區的 template.json 結構描述

共用方式為