教程：创建项模板Tutorial: Create an item template

本文内容

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

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

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

系统必备Prerequisites

参考文章介绍了有关模板的基础知识，以及如何将它们组合在一起。其中一些信息将在本文中重复出现。

  • 打开终端并导航到 working\templates\ 文件夹。

创建所需的文件夹Create the required folders

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

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

接下来，在名为“test” 的父文件夹下创建一个文件夹。文件夹结构应如下所示：

  1. parent_folder
  2. ├───test
  3. └───working
  4.     └───templates

创建项模板Create an item template

项模板是包含一个或多个文件的特定类型的模板。当你想要生成类似于配置、代码或解决方案文件的内容时，这些类型的模板非常有用。在本例中，你将创建一个类，该类将扩展方法添加到字符串类型中。

在终端中，导航到 working\templates\ 文件夹，并创建一个名为“extensions” 的新子文件夹。进入文件夹。

  1. working
  2. └───templates
  3.     └───extensions

创建一个名为“CommonExtensions.cs” 的新文件，并使用你喜爱的文本编辑器打开它。此类将提供一个用于反转字符串内容的名为 Reverse 的扩展方法。粘贴以下代码并保存文件：

  1. using System;
  3. namespace System
  4. {
  5.     public static class StringExtensions
  6.     {
  7.         public static string Reverse(this string value)
  8.         {
  9.             var tempArray = value.ToCharArray();
  10.             Array.Reverse(tempArray);
  11.             return new string(tempArray);
  12.         }
  13.     }
  14. }

现在你已经创建了模板的内容，需要在模板的根文件夹中创建模板配置。

创建模板配置Create the template config

模板在 .NET Core 中通过模板根目录中的特殊文件夹和配置文件进行识别。在本教程中，你的模板文件夹位于 working\templates\extensions\ 。

创建模板时，除特殊配置文件夹外，模板文件夹中的所有文件和文件夹都作为模板的一部分包含在内。此配置文件夹名为“.template.config” 。

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

  1. working
  2. └───templates
  3.     └───extensions
  4.         └───.template.config
  5.                 template.json

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

  1. {
  2.   "$schema": "http://json.schemastore.org/template",
  3.   "author": "Me",
  4.   "classifications": [ "Common", "Code" ],
  5.   "identity": "ExampleTemplate.StringExtensions",
  6.   "name": "Example templates: string extensions",
  7.   "shortName": "stringext",
  8.   "tags": {
  9.     "language": "C#",
  10.     "type": "item"
  11.   }
  12. }

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

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

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

  • 在 Windows 上：dotnet new -i .\
  • 在 Linux 或 macOS 上：dotnet new -i ./此命令输出安装的模板列表，其中应包括你的模板。
  1. C:\working\templates\extensions> dotnet new -i .\
  2. Usage: new [options]
  4. Options:
  5.   -h, --help          Displays help for this command.
  6.   -l, --list          Lists templates containing the specified name. If no name is specified, lists all templates.
  8. ... cut to save space ...
  10. Templates                                         Short Name            Language          Tags
  11. -------------------------------------------------------------------------------------------------------------------------------
  12. Example templates: string extensions              stringext             [C#]              Common/Code
  13. Console Application                               console               [C#], F#, VB      Common/Console
  14. Class library                                     classlib              [C#], F#, VB      Common/Library
  15. WPF Application                                   wpf                   [C#], VB          Common/WPF
  16. Windows Forms (WinForms) Application              winforms              [C#], VB          Common/WinForms
  17. Worker Service                                    worker                [C#]              Common/Worker/Web

测试项模板Test the item template

现在你已安装了项模板，可对其进行测试。导航到 test/ 文件夹，使用 dotnet new console 创建新的控制台应用程序。这将生成一个可以使用 dotnet run 命令轻松测试的工作项目。

  1. C:\test> dotnet new console
  2. The template "Console Application" was created successfully.
  4. Processing post-creation actions...
  5. Running 'dotnet restore' on C:\test\test.csproj...
  6.   Restore completed in 54.82 ms for C:\test\test.csproj.
  8. Restore succeeded.
  1. C:\test> dotnet run
  2. Hello World!

接下来，运行 dotnet new stringext 以从模板生成 CommonExtensions.cs 。

  1. C:\test> dotnet new stringext
  2. The template "Example templates: string extensions" was created successfully.

更改 Program.cs 中的代码以使用模板提供的扩展方法反转 "Hello World" 字符串。

  1. Console.WriteLine("Hello World!".Reverse());

再次运行程序，将看到结果已反转。

  1. C:\test> dotnet run
  2. !dlroW olleH

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

卸载模板Uninstall the template

由于模板是按文件路径安装的，因此，必须使用绝对 文件路径将其卸载。可以通过运行 dotnet new -u 命令看到已安装的模板列表。你的模板应列在最后。使用列出的路径，通过执行 dotnet new -u <ABSOLUTE PATH TO TEMPLATE DIRECTORY> 命令卸载模板。

  1. C:\working> dotnet new -u
  2. Template Instantiation Commands for .NET Core CLI
  4. Currently installed items:
  5.   Microsoft.DotNet.Common.ItemTemplates
  6.     Templates:
  7.       dotnet gitignore file (gitignore)
  8.       global.json file (globaljson)
  9.       NuGet Config (nugetconfig)
  10.       Solution File (sln)
  11.       Dotnet local tool manifest file (tool-manifest)
  12.       Web Config (webconfig)
  14. ... cut to save space ...
  16.   NUnit3.DotNetNew.Template
  17.     Templates:
  18.       NUnit 3 Test Project (nunit) C#
  19.       NUnit 3 Test Item (nunit-test) C#
  20.       NUnit 3 Test Project (nunit) F#
  21.       NUnit 3 Test Item (nunit-test) F#
  22.       NUnit 3 Test Project (nunit) VB
  23.       NUnit 3 Test Item (nunit-test) VB
  24.   C:\working\templates\extensions
  25.     Templates:
  26.       Example templates: string extensions (stringext) C#
  1. C:\working> dotnet new -u C:\working\templates\extensions

后续步骤Next steps

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

创建项目模板