共用方式為

教程：創建範本包

使用 .NET，您可以創建和部署生成專案、檔甚至資源的範本。 本教程是系列教程的第 3 部分，介紹如何創建、安裝和卸載用於該 dotnet new 命令的範本。

您可以在 .NET Samples GitHub 儲存庫中查看已完成的範本。

在本系列的這一部分中，您將學習如何：

先決條件

  • 完成本教程系列的第 1 部分 和 第 2 部分 。

    本教程使用在本教程系列的前兩部分中創建的兩個範本。 只要將範本作為資料夾複製到 working\content 資料夾中，就可以使用其他範本。

  • 打開終端並導航到 工作 資料夾。

  • 安裝 .NET 8 或 .NET 9。

  • Microsoft.TemplateEngine.Authoring.Templates從 NuGet 包源安裝範本。

    • dotnet new install Microsoft.TemplateEngine.Authoring.Templates從終端運行命令。

創建範本包專案

範本包是打包到 NuGet 包中的一個或多個範本。 安裝或卸載範本包時，將分別添加或刪除包中包含的所有範本。

範本包由 NuGet 包 （.nupkg） 檔表示。 而且，與任何 NuGet 包一樣，您可以將範本包上傳到 NuGet 源。 該 dotnet new install 命令支援從 NuGet 包源、 .nupkg 檔或包含範本的目錄安裝範本包。

通常，使用 C# 專案檔來編譯代碼並生成二進位檔。 但是，該專案也可用於生成範本包。 通過更改 .csproj 的設置，您可以阻止它編譯任何代碼，而是將範本的所有資產作為資源包含在內。 生成此專案時，它會生成範本包 NuGet 包。

您將要生成的包將包括之前創建的 項 和 工程 範本。

Microsoft.TemplateEngine.Authoring.Templates 包包含可用於範本創作的範本。 要安裝此包，nuget.org 應作為工作目錄中的 NuGet 源提供。

  1. 在 工作 資料夾中，執行以下命令以創建範本包：

    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.

  2. 接下來，在代碼編輯器中打開 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 ...

專案 XML 的說明

XML 代碼段中 下的 <PropertyGroup> 設置分為兩組。

第一組處理 NuGet 包所需的屬性。 這四個 <Package*> 設置與 NuGet 包屬性有關，用於在 NuGet 源上標識包。 該值 <PackageId> 雖然由 NuGet 使用，但也用於卸載範本包。 其餘設置（如 <Title> 和 <PackageTags>）與 NuGet 源和 .NET 包管理器上顯示的元數據有關。 有關 NuGet 設定的詳細資訊，請參閱 NuGet 和 MSBuild 屬性。

備註

要確保樣本包顯示在結果中 dotnet new search ， <PackageType> 必須設定為 Template。

在第二組中，該 <TargetFramework> 設置可確保在運行 pack 命令編譯和打包專案時 MSBuild 正常運行。 該組還包括與配置專案有關的設置，以便在創建 NuGet 包時將範本包含在 NuGet 包的相應資料夾中：

  • 該 <NoWarn> 設置將禁止顯示不適用於範本包專案的警告消息。

  • 該 <NoDefaultExcludes> 設置可確保以 . （like .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>

這很重要

內容內容資料夾包含一個 SampleTemplate 資料夾。 刪除 此資料夾，因為它已添加到創作範本中以進行演示。

這些 MSBuild 任務提供範本驗證和 範本功能的當地語系化 。 默認情況下，當地語系化處於禁用狀態。 要開啟本地化檔案的建立，請設定為 LocalizeTemplatestrue。

打包和安裝

儲存項目檔。 在構建範本包之前，請驗證您的資料夾結構是否正確。 要打包的任何範本都應放置在 content 資料夾自己的資料夾中。 資料夾結構應類似於以下層次結構：

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

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

在終端中，從 工作 資料夾中運行命令 dotnet pack 。 此命令生成專案並在 working\bin\Release 資料夾中創建一個 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>命令 <PackageId> where <PACKAGE_ID> is 與 .csproj 檔中的設置相同。

卸載範本包

無論您如何安裝範本包，無論是直接使用 .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 的自定義範本新 文章。