教程：创建项目模板

项目
10/07/2023

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

提示

可以在以下存储库中找到随 .NET SDK 提供的官方 .NET 模板：

模板	存储库
控制台、类库和公共项模板	dotnet/sdk
ASP.NET 和 Blazor 模板	dotnet/aspnetcore
ASP.NET 单页应用程序模板	dotnet/spa-templates
WPF 模板	dotnet/wpf
Windows 窗体模板	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

测试项目模板

现在你已安装了项目模板，可对其进行测试。

导航到test文件夹。
使用以下命令新建控制台应用程序，该命令生成可使用dotnet run命令轻松测试的工作项目。
```
dotnet new consoleasync -n MyProject
```
将获得以下输出。
```
The template "Example templates: async project" was created successfully.
```
请使用以下命令运行项目。
```
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 查看已安装的模板包列表，包括每个模板包的卸载命令。

后续步骤

在本教程中，你创建了一个项目模板。若要了解如何将项模板和项目模板打包为易于使用的文件，请继续学习本教程系列。

创建模板包