.NET Core 编程指南中文版 —— 2.14 入门 -> 创建 dotnet new 自定义模板

本教程介绍了如何：

• 通过现有项目或新控制台应用程序项目创建基本模板。
• 从 nuget.org 或本地 nupkg 文件打包模板以供分发。
• 从 nuget.org、本地 nupkg 文件或本地文件系统安装模板。
• 卸载模板。

若要通过完整示例继续学习本教程，请下载示例项目模板。 示例模板针对 NuGet 分发进行了配置。

若要将下载的示例与文件系统分发相结合，请按照以下步骤操作：

• 将示例中 content 文件夹的内容移到上一级 GarciaSoftware.ConsoleTemplate.CSharp 文件夹中。
• 删除空的 content 文件夹。
• 删除 nuspec 文件。

系统必备

• 安装 .NET Core 2.0 SDK 或更高版本。
• 阅读参考主题 dotnet new 自定义模板。

通过项目创建模板

使用已确认的可以编译和运行的现有项目，或在硬盘上的文件夹中新建一个控制台应用项目。 本教程假定项目文件夹名为 GarciaSoftware.ConsoleTemplate.CSharp，并存储在用户配置文件 Documents\Templates下。 本教程的项目模板名称采用格式“<公司名称>.<模板类型>.<编程语言>”，但也可以根据自己的意愿随意命名项目和模板。

1. 向项目根目录下添加一个文件夹，命名为 .template.config。
2. 在 .template.config 文件夹下，创建一个 template.json 文件来配置您的模板。 有关 template.json 文件的详细信息和成员定义，请参阅 dotnet new 自定义模板主题和 JSON 架构存储中的 template.json 架构。

{
    "$schema": "http://json.schemastore.org/template",
    "author": "Catalina Garcia",
    "classifications": [ "Common", "Console" ],
    "identity": "GarciaSoftware.ConsoleTemplate.CSharp",
    "name": "Garcia Software Console Application",
    "shortName": "garciaconsole"
}

模板已完成。 此时，可通过两种方式分发模板。 若要继续阅读本教程，请选择下面两种路径之一：

1. NuGet 分发：从 NuGet 或本地 nupkg 文件安装模板，并使用安装后的模板。
2. 文件系统分发。

使用 NuGet 分发

将模板打包到 NuGet 包中

1. 为 NuGet 包创建文件夹。 在本教程中，使用的文件夹名为 GarciaSoftware.ConsoleTemplate.CSharp，该文件夹在用户配置文件中的 Documents\NuGetTemplates 内创建。 在新建的模板文件夹内，创建名为 content 的文件夹，以保存项目文件。

2. 将项目文件夹的内容连同 .template.config/template.json 文件一起复制到创建的 content 文件夹中。

3. 在 content 文件夹旁边，添加 nuspec 文件。 nuspec 文件是 XML 清单文件，用于描述包内容，并促进创建 NuGet 包。

   

4. 在 nuspec文件的 <packageTypes> 元素中，添加 name 属性值为 Template 的 <packageType> 元素。 content 文件夹和 nuspec 文件应位于同一目录。 下表列出了将模板生成为 NuGet 包至少所需的 nuspec 文件元素。

   元素	类型	说明
   <authors>	字符串	包创建者的逗号分隔列表，与 nuget.org 上的配置文件名称一致。创建者显示在 nuget.org 上的 NuGet 库中，用于交叉引用同一创建者的包。
   <description>	字符串	用于 UI 显示的包的详细说明。
   <id>	字符串	不区分大小写的包标识符，在 nuget.org 或包驻留的任意库中必须是唯一的。 ID 不得包含空格或对 URL 无效的字符，通常遵循 .NET 命名空间规则。 有关指南，请参阅选择唯一包标识符并设置版本号。
   <packageType>	字符串	将此元素置于 <metadata> 元素之间的 <packageTypes> 元素内。 将 <packageType> 元素的 name 属性设置为 Template。
   <version>	字符串	遵循 major.minor.patch 模式的包版本。 版本号可能包括预发布后缀，如预发布版本中所述。

   有关完整的 nuspec 文件架构，请参阅 .nuspec 参考。

   在本教程中，nuspec 文件命名为 GarciaSoftware.ConsoleTemplate.CSharp.nuspec，包含以下内容：

   <?xml version="1.0" encoding="utf-8"?>
   <package xmlns="http://schemas.microsoft.com/packaging/2012/06/nuspec.xsd">
     <metadata>
       <id>GarciaSoftware.ConsoleTemplate.CSharp</id>
       <version>1.0.0</version>
       <description>
         Creates the Garcia Software console app.
       </description>
       <authors>Catalina Garcia</authors>
       <packageTypes>
         <packageType name="Template" />
       </packageTypes>
     </metadata>
   </package>
   

5. 使用 nuget pack <PATH_TO_NUSPEC_FILE> 命令创建包。 以下命令假定包含 NuGet 资产的文件夹位于 C:\Users\<USER>\Documents\Templates\GarciaSoftware.ConsoleTemplate.CSharp。 不过，无论将文件夹放置在系统上的什么位置，nuget pack 命令都接受 nuspec 文件路径：

   nuget pack C:\Users\<USER>\Documents\NuGetTemplates\GarciaSoftware.ConsoleTemplate.CSharp\GarciaSoftware.ConsoleTemplate.CSharp.nuspec
   

将包发布到 nuget.org

若要发布 NuGet 包，请按照创建和发布包主题中的说明操作。 不过，不建议将本教程的模板发布到 NuGet，因为一旦发布，便永远无法删除，只能从列表去除。 至此已拥有 nupkg 文件形式的 NuGet 包，建议按照下面的说明操作，直接从本地 nupkg 文件安装模板。

从 NuGet 包安装模板

从本地 nupkg 文件安装模板

若要从生成的 nupkg 文件安装模板，请结合使用 dotnet new 命令和 -i|--install 选项，并提供 nupkg 文件路径：

dotnet new -i C:\Users\<USER>\GarciaSoftware.ConsoleTemplate.CSharp.1.0.0.nupkg

从 nuget.org 中存储的 NuGet 包安装模板

若要从 nuget.org 中存储的 NuGet 包安装模板，请结合使用 dotnet new 命令和 -i|--install 选项，并提供 NuGet 包名称：

dotnet new -i GarciaSoftware.ConsoleTemplate.CSharp

 备注

示例代码只为了方便本文演示。 如果 nuget.org 中没有 GarciaSoftware.ConsoleTemplate.CSharpNuGet 包，不建议发布并从 NuGet 使用测试模板。 如果运行此命令，不会安装任何模板。 不过，可以安装尚未发布到 nuget.org 的模板，具体方法是直接在本地文件系统上引用 nupkg 文件，如前一部分从本地 nupkg 文件安装模板所述。

如果需要获取有关如何从 nuget.org 中的包安装模板的实际示例，可以使用 dotnet-new 的 NUnit 3 模板。 此模板将项目设置为使用 NUnit 单元测试。 运行以下命令安装此模板：

dotnet new -i NUnit3.DotNetNew.Template

使用 dotnet new -l 列出模板时，模板列表中会列出短名称为“nunit”的“NUnit 3 测试项目”。 可以在下一部分中使用此模板了。

通过模板创建项目

从 NuGet 安装模板后，在要放置模板引擎输出的目录（除非使用 -o|--output 选项指定特定的目录）执行 dotnet new <TEMPLATE> 命令，即可使用模板。 有关详细信息，请参阅 dotnet new 选项。直接向 dotnet new 命令提供模板的短名称。 若要通过 NUnit 模板创建项目，请运行以下命令：

dotnet new nunit

控制台显示项目已创建，且项目包已还原。 运行此命令后，项目便可供使用。

从 nuget.org 中存储的 NuGet 包卸载模板的具体步骤

dotnet new -u GarciaSoftware.ConsoleTemplate.CSharp

 备注

示例代码只为了方便本文演示。 GarciaSoftware.ConsoleTemplate.CSharp NuGet 包没有存储到 nuget.org 或与 .NET Core SDK 一起安装。 如果运行此命令，不会卸载任何包/模板，并会看到以下异常消息：

找不到要卸载的“GarciaSoftware.ConsoleTemplate.CSharp”包/模板。

若要卸载已安装的 dotnet-new 的 NUnit 3 模板，请运行以下命令：

dotnet new -u NUnit3.DotNetNew.Template

从本地 nupkg 文件卸载模板

若要卸载模板，请勿尝试使用 nupkg 文件路径。 无法尝试使用 dotnet new -u <PATH_TO_NUPKG_FILE>卸载模板。 按 id 引用包：

dotnet new -u GarciaSoftware.ConsoleTemplate.CSharp.1.0.0

使用文件系统分发

若要分发模板，请确保用户可以在网络*问项目模板文件夹的位置。 结合使用 dotnet new 命令和 -i|--install 选项，并指定模板文件夹路径（包含项目和 .template.config 文件夹的项目文件夹）。

本教程假定项目模板存储在用户配置文件中的 Documents/Templates 文件夹内。 从这个位置，使用以下命令安装模板，只将 <USER> 替换为用户的配置文件名称：

dotnet new -i C:\Users\<USER>\Documents\Templates\GarciaSoftware.ConsoleTemplate.CSharp

通过模板创建项目

从文件系统安装模板后，在要放置模板引擎输出的目录（除非使用 -o|--output 选项指定特定的目录）执行 dotnet new <TEMPLATE> 命令，即可使用模板。 有关详细信息，请参阅 dotnet new 选项。直接向 dotnet new 命令提供模板的短名称。

从 C:\Users\<USER>\Documents\Projects\MyConsoleApp 处创建的新项目文件夹，通过 garciaconsole 模板创建项目：

dotnet new garciaconsole

卸载模板

如果在本地文件系统中的 C:\Users\<USER>\Documents\Templates\GarciaSoftware.ConsoleTemplate.CSharp 处创建模板，请使用 -u|--uninstall 开关和模板文件夹路径卸载模板：

dotnet new -u C:\Users\<USER>\Documents\Templates\GarciaSoftware.ConsoleTemplate.CSharp

 备注

若要从本地文件系统卸载模板，需要完全限定路径。 例如，C:\Users\<USER>\Documents\Templates\GarciaSoftware.ConsoleTemplate.CSharp 有效，但是包含文件夹中的 ./GarciaSoftware.ConsoleTemplate.CSharp 无效。 此外，模板路径中不要包含最后的终止目录斜杠。

请参阅

• dotnet/templating GitHub 存储库 Wiki
• dotnet/dotnet-template-samples GitHub 存储库
• 如何创建自己的 dotnet new 模板
• JSON 架构存储中的 template.json 架构