教程：创建模板包

项目
12/31/2024

使用 .NET，可以创建和部署用于生成项目、文件甚至资源的模板。本教程是一系列教程的第三部分，介绍如何创建、安装和卸载模板，以便与 dotnet new 命令一起使用。

可以在 .NET 示例 GitHub 存储库中查看已完成的模板。

在本系列的这一部分中，你将了解如何：

使用 Microsoft.TemplateEngine.Authoring.Templates NuGet 包创建模板包。
从 NuGet 包文件安装模板包。
按包 ID 卸载模板包。

先决条件

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

本教程使用本教程系列前两部分创建的两个模板。只要将模板作为文件夹复制到 工作\内容 文件夹中，就可以使用不同的模板。
打开终端并导航到工作文件夹。
安装 .NET 8 或 .NET 9。
从 NuGet 包源安装 Microsoft.TemplateEngine.Authoring.Templates 模板。
- 从终端运行 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 源提供。

在工作文件夹中，运行以下命令以创建模板包：

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 ...

项目 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 包时，将模板包含在正确的文件夹中：

<NoWarn> 设置禁止显示不适用于模板包项目的警告消息。
<NoDefaultExcludes> 设置可确保以 .（如 .gitignore）开头的文件和文件夹是模板的一部分。 NuGet 包的默认行为是忽略这些文件和文件夹。

<ItemGroup> 包含两个项。首先，<Content> 项包括模板文件夹中的所有内容作为内容。它还设置为排除任何 bin 文件夹或 obj 文件夹，以防止包含任何已编译的代码（如果已测试和编译模板）。其次，<Compile> 项将所有代码文件排除在编译范围之外，无论它们位于何处都是如此。此设置可防止用于创建模板包的项目尝试在模板文件夹层次结构中编译代码。

提示

有关 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。

打包并安装

保存项目文件。在生成模板包之前，请验证文件夹结构是否正确。任何要打包的模板都应放在模板文件夹里的独立文件夹中。文件夹结构应类似于以下层次结构：

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

content 文件夹中有两个文件夹：extensions 和 consoleasync。

在终端中的 working 文件夹中，运行 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> 命令，其中 <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 自定义模板一文。

通过