教程：创建项模板

项目
10/07/2023

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

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

提示

Visual Studio 的“添加”>“新项”对话框中不显示项模板。

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

为项模板创建类。
创建模板配置文件夹和文件。
从文件路径安装模板。
测试项模板。
卸载项模板。

先决条件

.NET SDK 7.0.100 或更高版本。

参考文章介绍了有关模板的基础知识，以及如何将它们组合在一起。此处重申了其中一些信息。
打开一个终端并导航到要在其中存储和测试模板的文件夹。

重要

本文针对 .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 命令查看所有选项和子命令的列表。

创建所需的文件夹

本系列使用包含模板源的“working 文件夹”和用于测试模板的“testing 文件夹”。 working 文件夹和 testing 文件夹应位于同一父文件夹下。

首先，创建父文件夹，名称无关紧要。然后，创建两个名为“working”和“test”的子文件夹。在“working”文件夹内，创建一个名为“content”的子文件夹。

文件夹结构应如下所示。

parent_folder
├───test
└───working
    └───content

创建项模板

项模板是包含一个或多个文件的特定类型的模板。当你已有一个项目并且想要生成另一个文件（例如配置文件或代码文件）时，这些类型的模板非常有用。在本例中，你将创建一个类，该类将扩展方法添加到字符串类型中。

在终端中，导航到 working\content 文件夹，并新建一个名为 extensions 的子文件夹。

working
└───content
    └───extensions

导航到 extensions 文件夹并创建一个名为 StringExtensions.cs 的新文件。在文本编辑器中打开文件。此类将提供一个用于反转字符串内容的名为 Reverse 的扩展方法。粘贴以下代码并保存文件：

namespace System;

public static class StringExtensions
{
    public static string Reverse(this string value)
    {
        char[] tempArray = value.ToCharArray();
        Array.Reverse(tempArray);
        return new string(tempArray);
    }
}

现在模板的内容已完成，下一步是创建模板配置。

创建模板配置

在教程的本部分中，你的模板文件夹位于 working\content\extensions。

.NET 识别模板，因为它们在模板文件夹的根目录中存在一个特殊的文件夹和配置文件。

首先，新建名为.template.config的子文件夹，然后进入该文件夹。然后，创建一个名为“template.json” 的新文件。文件夹结构应如下所示：

working
└───content
    └───extensions
        └───.template.config
                template.json

使用你喜爱的文本编辑器打开 template.json 并粘贴以下 JSON 代码，然后保存。

{
    "$schema": "http://json.schemastore.org/template",
    "author": "Me",
    "classifications": [ "Common", "Code" ],
    "identity": "ExampleTemplate.StringExtensions",
    "name": "Example templates: string extensions",
    "shortName": "stringext",
    "tags": {
      "language": "C#",
      "type": "item"
    },
    "symbols": {
      "ClassName":{
        "type": "parameter",
        "description": "The name of the code file and class.",
        "datatype": "text",
        "replaces": "StringExtensions",
        "fileRename": "StringExtensions",
        "defaultValue": "StringExtensions"
      }
    }
  }

此配置文件包含模板的所有设置。可以看到基本设置，例如name和shortName，除此之外，还有设置为item的tags/type值。这会将你的模板归类为“项”模板。你创建的模板类型不存在限制。 item 和 project 值是 .NET 建议使用的通用名称，便于用户轻松筛选正在搜索的模板类型。

classifications 项表示你在运行 dotnet new 并获取模板列表时看到的“标记” 列。用户还可以根据分类标记进行搜索。不要将 template.json 文件中的 tags 属性与 classifications 标记列表混淆。它们是两个不同的概念，不幸的是名称相同。 template.json文件的完整架构位于JSON 架构存储，并在template.json 参考中进行描述。。有关 template.json 文件的详细信息，请参阅 dotnet 创建模板 wiki。

此 JSON 对象的 symbols 部分用于定义可在模板中使用的参数。在本例中，定义了一个参数 ClassName。定义的参数包含以下设置：

type - 这是一个强制设置，必须设置为 parameter。
description - 参数的说明，这将在模板帮助中输出。
datatype - 使用此参数时参数值的数据类型。
replaces - 指定在所有模板文件中应由此参数值替换的一个文本值。
fileRename - 类似于 replaces，指定在所有模板文件的名称中由此参数值替换的一个文本值。
defaultValue - 当用户未指定此参数时，此参数的默认值。

使用模板时，用户可以为 ClassName 参数提供一个值，此值将替换 StringExtensions 的所有匹配项。如果未提供值，则使用 defaultValue。对于此模板，StringExtensions 有两个匹配项：文件 StringExtensions.cs 和类 StringExtensions。由于此参数的 defaultValue 是 StringExtensions，因此，如果在使用模板时未指定此参数，则文件名和类名将保持不变。当指定了某个值时，例如 dotnet new stringext -ClassName MyExts，则该文件将被重命名为 MyExts.cs，该类将被重命名为 MyExts。

若要查看可用于某个模板的参数，请对模板名称使用 -? 参数：

dotnet new stringext -?

这会生成以下输出：

Example templates: string extensions (C#)
Author: Me

Usage:
  dotnet new stringext [options] [template options]

Options:
  -n, --name <name>       The name for the output being created. If no name is specified, the name of the output directory is used.
  -o, --output <output>   Location to place the generated output.
  --dry-run               Displays a summary of what would happen if the given command line were run if it would result in a template creation.
  --force                 Forces content to be generated even if it would change existing files.
  --no-update-check       Disables checking for the template package updates when instantiating a template.
  --project <project>     The project that should be used for context evaluation.
  -lang, --language <C#>  Specifies the template language to instantiate.
  --type <item>           Specifies the template type to instantiate.

Template options:
  -C, --ClassName <ClassName>  The name of the code file and class.
                               Type: text
                               Default: StringExtensions

现在你已有一个有效的 .template.config/template.json 文件，可以安装模板了。在终端中，导航到 extensions 文件夹，并运行以下命令以安装位于当前文件夹的模板：

在 Windows 上：dotnet new install .\
在 Linux 或 macOS 上：dotnet new install ./

此命令输出安装的模板列表，其中应包括你的模板。

The following template packages will be installed:
   <root path>\working\content\extensions

Success: <root path>\working\content\extensions installed the following templates:
Templates                                         Short Name               Language          Tags
--------------------------------------------      -------------------      ------------      ----------------------
Example templates: string extensions              stringext                [C#]              Common/Code

测试项模板

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

导航到 test 文件夹。

使用 dotnet new console 创建一个新的控制台应用程序，该命令生成可使用 dotnet run 命令轻松测试的工作项目。

dotnet new console

将获得类似于下面的输出。

The template "Console Application" was created successfully.

Processing post-creation actions...
Running 'dotnet restore' on C:\test\test.csproj...
  Restore completed in 54.82 ms for C:\test\test.csproj.

Restore succeeded.

请使用以下命令运行项目。
```
dotnet run
```
将获得以下输出。
```
Hello, World!
```

运行 dotnet new stringext 以基于模板生成 StringExtensions.cs 文件。

dotnet new stringext

将获得以下输出。

The template "Example templates: string extensions" was created successfully.

更改 Program.cs 中的代码以使用模板提供的扩展方法反转 "Hello, World!" 字符串。
```
Console.WriteLine("Hello, World!".Reverse());
```
再次运行程序，将看到结果已反转。
```
dotnet run
```
将获得以下输出。
```
!dlroW ,olleH
```

祝贺你！你已使用 .NET 创建并部署了项模板。为准备学习本系列教程的下一部分，卸载已创建的模板。请确保同时删除 test 文件夹中的所有文件和文件夹。这会回到干净状态，为本教程系列的下一部分做好准备。

卸载模板

在终端中，导航到 extensions 文件夹，并运行以下命令以卸载位于当前文件夹的模板：

在 Windows 上：dotnet new uninstall .\
在 Linux 或 macOS 上：dotnet new uninstall ./

此命令输出已卸载的模板列表，其中应包括你的模板。

Success: <root path>\working\content\extensions was uninstalled.

随时可以使用 dotnet new uninstall 查看已安装的模板包列表，包括每个模板包的卸载命令。

后续步骤

在本教程中，你创建了一个项模板。若要了解如何创建项目模板，请继续学习本系列教程。

创建项目模板