dotnet new 自定义模板Custom templates for dotnet new

本文内容

.NET Core SDK 随附了许多已安装并可供你使用的模板。dotnet new 命令不仅用于使用模板，还用于说明如何安装和卸载模板。自.NET Core 2.0 起，可以为任何类型的项目（如应用程序、服务、工具或类库）创建自己的自定义模板。甚至可以创建输出一个或多个独立文件（如配置文件）的模板。

可以从任何 NuGet 源上的 NuGet 包安装自定义模板，具体方法是直接引用 NuGet .nupkg 文件，或指定包含模板的文件系统目录。借助模板引擎提供的功能，可以替换值、包括和排除文件，并在使用模板时执行自定义处理操作。

模板引擎是开放源代码，在线代码存储库位于 GitHub 上的 dotnet/templating。有关模板示例，请访问 dotnet/dotnet-template-samples 存储库。GitHub 上的 dotnet new 可用模板收录了更多模板，包括第三方模板。若要详细了解如何创建和使用自定义模板，请参阅如何创建自己的 dotnet new 模板和 dotnet/templating GitHub 存储库 Wiki。

若要按照演示步骤操作并创建模板，请参阅创建 dotnet new 自定义模板教程。

.NET 默认模板.NET default templates

安装 .NET Core SDK 时，将获取十多个用于创建项目和文件的内置模板，包括控制台应用程序、类库、单元测试项目、ASP.NET Core 应用程序（包括 Angular 和 React 项目）和配置文件。若要列出内置模板，请运行带有 -l|—list 选项的 dotnet new 命令：

  1. dotnet new --list

配置Configuration

模板由以下部分组成：

  • 源文件和文件夹。
  • 配置文件 (template.json )。

源文件和文件夹Source files and folders

源文件和文件夹包含运行 dotnet new <TEMPLATE> 命令时用户希望模板引擎使用的任何文件和文件夹。模板引擎旨在将可运行项目 用作源代码，以生成项目。这样做有以下几个好处：

  • 模板引擎不要求用户将特殊令牌注入项目的源代码。
  • 代码文件不必是特殊文件，也不必以任何方式进行修改，即可与模板引擎配合使用。因此，处理项目时通常使用的工具也适用于模板内容。
  • 生成、运行和调试模板项目，就像生成、运行和调试其他任何项目一样。
  • 只需将 ./.template.config/template.json 配置文件添加到项目，即可通过现有项目快速创建模板。模板中存储的文件和文件夹并不限于正式的 .NET 项目类型。源文件和文件夹可能包含用户希望在使用模板时创建的任何内容，即使模板引擎仅生成一个文件作为输出也不例外。

可以基于在 template.json 配置文件中提供的逻辑和设置对模板生成的文件进行修改。用户可以将选项传递到 dotnet new <TEMPLATE> 命令以覆盖这些设置。自定义逻辑的一个常见示例为模板部署的代码文件中的类或变量提供名称。

template.jsontemplate.json

template.json 文件位于模板根目录中的 .template.config 文件夹。此文件向模板引擎提供配置信息。最低配置必须包含下表中列出的成员，这足以创建功能模板。

成员类型说明
$schemaURItemplate.json 文件的 JSON 架构。如果指定架构，支持 JSON 架构的编辑器启用 JSON 编辑功能。例如，Visual Studio Code 要求此成员启用 IntelliSense。使用值 http://json.schemastore.org/template。
authorstring模板创建者。
classificationsarray(string)为了找到模板，用户可能会在搜索模板时使用的 0 个或多个模板特征。如果出现在使用 dotnet new -l|—list 命令生成的模板列表中，classifications 还会出现在“Tags” 列中。
identitystring此模板的唯一名称。
namestring用户应看到的模板名称。
shortNamestring方便用户选择模板的默认速记名称，适用于模板名称由用户指定（而不是通过 GUI 选择）的环境。例如，通过命令提示符和 CLI 命令使用模板时，短名称非常有用。

template.json 文件的完整架构位于 JSON 架构存储。有关 template.json 文件的详细信息，请参阅 dotnet 创建模板 wiki。

示例Example

例如，下面是包含两个内容文件的模板文件夹：console.cs 和 readme.txt 。请注意，其中有包含 template.json 文件的名为 .template.config 的所需文件夹。

  1. └───mytemplate
  2.     │   console.cs
  3.     │   readme.txt
  4.     │
  5.     └───.template.config
  6.             template.json

template.json 文件如下所示：

  1. {
  2.   "$schema": "http://json.schemastore.org/template",
  3.   "author": "Travis Chau",
  4.   "classifications": [ "Common", "Console" ],
  5.   "identity": "AdatumCorporation.ConsoleTemplate.CSharp",
  6.   "name": "Adatum Corporation Console Application",
  7.   "shortName": "adatumconsole"
  8. }

mytemplate 文件夹是可安装的模板包。安装此包后，shortName 可与 dotnet new 命令结合使用。例如，dotnet new adatumconsole 会将 console.cs 和 readme.txt 文件输出到当前文件夹。

将模板打包到 NuGet 包（nupkg 文件）Packing a template into a NuGet package (nupkg file)

自定义模板与 dotnet pack 命令和 .csproj 文件一起打包。或者，NuGet 可与 nuget pack 命令以及 .nuspec 文件一起使用。但是，NuGet 在 Windows 上需要 .NET Framework，在 Linux 和 MacOS 上需要 Mono。

该 .csproj 文件与传统代码项目 .csproj 文件略有不同。请注意以下设置：

  • 添加 <PackageType> 设置并将其设为 Template。
  • 添加 <PackageVersion> 设置并将其设为有效的 NuGet 版本号。
  • 添加 <PackageId> 设置并将其设为唯一标识符。此标识符用于卸载模板包，NuGet 源用它来注册你的模板包。
  • 应设置泛型元数据设置：<Title>、<Authors>、<Description> 和 <PackageTags>。

  • 必须设置 <TargetFramework> 设置，即使未使用模板过程生成的二进制文件也必须设置。在下面的示例中，它设置为 netstandard2.0。.nupkg NuGet 包形式的模板包要求所有模板都存储在包中的 content 文件夹中。还有几个设置将添加到 .csproj 文件以确保生成的 .nupkg 作为模板包安装：

  • <IncludeContentInPack> 设置设为 true 以包含项目在 NuGet 包中设为“内容”的任何文件 。

  • <IncludeBuildOutput> 设置设为 false 以从 NuGet 包排除编译器生成的所有二进制文件。
  • <ContentTargetFolders> 设置设为 content。这可确保设为“内容” 的文件存储在 NuGet 包的 content 文件夹中。NuGet 包中的此文件夹由 dotnet 模板系统解析。使所有代码文件不被模板项目编译的一个简单的方法是使用 <ItemGroup> 元素内项目文件中的 <Compile Remove="*\" /> 项。

设置模板包结构的一个简单方法是将所有模板放在单独的文件夹中，然后放到位于 .csproj 文件所在目录的 templates 文件夹的每个模板文件夹中 。这样，你可以使用单个项目项包括 templates 中的所有文件和文件夹作为“内容” 。在 <ItemGroup> 元素中创建 <Content Include="templates*\" Exclude="templates*\bin*;templates**\obj\" /> 项。

下面是一个遵循上述所有准则的示例 .csproj 文件。它将 templates 子文件夹打包为“内容” 包文件夹，并使所有代码文件都不被编译。

  1. <Project Sdk="Microsoft.NET.Sdk">
  3.   <PropertyGroup>
  4.     <PackageType>Template</PackageType>
  5.     <PackageVersion>1.0</PackageVersion>
  6.     <PackageId>AdatumCorporation.Utility.Templates</PackageId>
  7.     <Title>AdatumCorporation Templates</Title>
  8.     <Authors>Me</Authors>
  9.     <Description>Templates to use when creating an application for Adatum Corporation.</Description>
  10.     <PackageTags>dotnet-new;templates;contoso</PackageTags>
  11.     <TargetFramework>netstandard2.0</TargetFramework>
  13.     <IncludeContentInPack>true</IncludeContentInPack>
  14.     <IncludeBuildOutput>false</IncludeBuildOutput>
  15.     <ContentTargetFolders>content</ContentTargetFolders>
  16.   </PropertyGroup>
  18.   <ItemGroup>
  19.     <Content Include="templates\**\*" Exclude="templates\**\bin\**;templates\**\obj\**" />
  20.     <Compile Remove="**\*" />
  21.   </ItemGroup>
  23. </Project>

以下示例演示使用 .csproj 创建模板包的文件和文件夹结构。MyDotnetTemplates.csproj 文件和 templates 文件夹都位于名为 project_folder 的根目录中。templates 文件夹包含两个模板 mytemplate1 和 mytemplate2 。每个模板具有内容文件和包含 template.json 配置文件的 .template.config 文件夹。

  1. project_folder
  2. │   MyDotnetTemplates.csproj
  3. │
  4. └───templates
  5.     ├───mytemplate1
  6.     │   │   console.cs
  7.     │   │   readme.txt
  8.     │   │
  9.     │   └───.template.config
  10.     │           template.json
  11.     │
  12.     └───mytemplate2
  13.         │   otherfile.cs
  14.         │
  15.         └───.template.config
  16.                 template.json

安装模板Installing a template

使用 dotnet new -i|—install 命令以安装包。

从 nuget.org 中存储的 NuGet 包安装模板的具体步骤To install a template from a NuGet package stored at nuget.org

使用 NuGet 包标识符安装模板包。

  1. dotnet new -i <NUGET_PACKAGE_ID>

从本地 nupkg 文件安装模板的具体步骤To install a template from a local nupkg file

提供指向 .nupkg NuGet 包文件的路径。

  1. dotnet new -i <PATH_TO_NUPKG_FILE>

从文件系统目录安装模板的具体步骤To install a template from a file system directory

模板可从模板文件夹安装，如以上示例中的 mytemplate1 文件夹。指定 .template.config 文件夹的文件夹路径。模板目录的路径不需要是绝对路径。但是，卸载从文件夹安装的模板时需要绝对路径。

  1. dotnet new -i <FILE_SYSTEM_DIRECTORY>

获取已安装模板的列表Get a list of installed templates

在没有任何其他参数的情况下，卸载命令将列出所有已安装的模板。

  1. dotnet new -u

该命令返回如下所示的输出：

  1. Template Instantiation Commands for .NET Core CLI
  3. Currently installed items:
  4.   Microsoft.DotNet.Common.ItemTemplates
  5.     Templates:
  6.       global.json file (globaljson)
  7.       NuGet Config (nugetconfig)
  8.       Solution File (sln)
  9.       Dotnet local tool manifest file (tool-manifest)
  10.       Web Config (webconfig)
  11.   Microsoft.DotNet.Common.ProjectTemplates.3.0
  12.     Templates:
  13.       Class library (classlib) C#
  14.       Class library (classlib) F#
  15.       Class library (classlib) VB
  16.       Console Application (console) C#
  17.       Console Application (console) F#
  18.       Console Application (console) VB
  19. ...

Currently installed items: 后面的第一级项是用于卸载模板的标识符。在上述示例中，列出了 Microsoft.DotNet.Common.ItemTemplates 和 Microsoft.DotNet.Common.ProjectTemplates.3.0。如果使用文件系统路径安装模板，此标识符将是 .template.config 文件夹的文件夹路径。

卸载模板Uninstalling a template

使用 dotnet new -u|—uninstall 命令卸载包。

如果通过 NuGet 源或直接通过 .nupkg 文件安装包，请提供标识符。

  1. dotnet new -u <NUGET_PACKAGE_ID>

如果通过指定 .template.config 文件夹的路径安装包，请使用该绝对 路径卸载包。你可以在 dotnet new -u 命令提供的输出中看到模板的绝对路径。有关详细信息，请参阅上文的获取已安装的模板列表部分。

  1. dotnet new -u <ABSOLUTE_FILE_SYSTEM_DIRECTORY>

使用自定义模板创建项目Create a project using a custom template

安装模板后，通过执行 dotnet new <TEMPLATE> 命令来使用模板，就像使用其他任何预安装模板一样。还可以为 dotnet new 命令指定选项，包括在模板设置中配置的模板专用选项。直接向命令提供模板的短名称：

  1. dotnet new <TEMPLATE>

请参阅See also