dotnet new 的自定义模板

2025-06-19

.NET SDK 附带许多已安装的模板，可供你使用。该 dotnet new 命令不仅是使用模板的方法，也是如何安装和卸载模板的方法。可以为任何类型的项目（例如应用、服务、工具或类库）创建自定义模板。甚至可以创建一个模板来输出一个或多个独立文件，例如配置文件。

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

模板引擎是开源的，联机代码存储库位于 GitHub 上的 dotnet/templating 中。可以通过 dotnet new search 找到更多模板，包括来自第三方的模板。有关创建和使用自定义模板的详细信息，请参阅如何为 dotnet new 和 dotnet/templating GitHub 存储库 Wiki 创建自己的模板。

注释

模板示例在 dotnet/templating GitHub 存储库中提供。

要按照操作指南创建模板，请参阅创建用于 dotnet new 的自定义模板教程。

.NET 默认模板

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

dotnet new list

配置

模板由以下部分组成：

源文件和文件夹。
配置文件（template.json）。

源文件和文件夹

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

模板引擎不需要将特殊令牌注入到项目的源代码中。
代码文件不是特殊文件，也不以任何方式修改以使用模板引擎。因此，使用项目时通常使用的工具也适用于模板内容。
生成、运行和调试模板项目，就像对任何其他项目所做的那样。
只需将 ./.template.config/template.json 配置文件添加到项目，即可从现有项目快速创建模板。

存储在模板中的文件和文件夹不限于正式的 .NET 项目类型。源文件和文件夹可能包含希望在使用模板时创建的任何内容，即使模板引擎只生成一个文件作为其输出。

可以根据 template.json配置文件中 提供的逻辑和设置修改模板生成的文件。用户可以通过将选项传递给 dotnet new <TEMPLATE> 命令来替代这些设置。自定义逻辑的一个常见示例是为模板部署的代码文件中的类或变量提供名称。

template.json

template.json 文件放置在模板根目录中的.template.config 文件夹中。该文件向模板引擎提供配置信息。最低配置需要下表中显示的成员，这足以创建功能模板。

成员	类型	DESCRIPTION
`$schema`	URI	template.json 文件的 JSON 架构。支持 JSON 架构的编辑器在指定架构时启用 JSON 编辑功能。例如， Visual Studio Code 要求此成员启用 IntelliSense。使用值 `http://json.schemastore.org/template`。
`author`	字符串	模板的作者。
`classifications`	array（string）	为了找到模板，用户可能会在搜索模板时使用的 0 个或多个模板特征。当分类显示在使用命令生成的模板列表中时，分类也会显示在`dotnet new list`”列中。
`identity`	字符串	此模板的唯一名称。
`name`	字符串	用户应看到的模板的名称。
`shortName`	字符串	方便用户选择模板的默认速记名称，适用于模板名称由用户指定（而不是通过 GUI 选择）的环境。例如，使用命令提示符中的模板和 CLI 命令时，短名称非常有用。
`sourceName`	字符串	源树中的名称，它即将替换为用户指定的名称。模板引擎将查找配置文件中提及并出现的任何 `sourceName`，并将其替换为文件名和文件内容。可以在运行模板时使用 `-n` 或 `--name` 选项提供要替换为的值。如果未指定任何名称，则使用当前目录。
`preferNameDirectory`	布尔型	指示指定名称但未设置输出目录（而不是直接在当前目录中创建内容）时是否为模板创建目录。默认值为 false。

在 JSON 架构存储中找到 template.json 文件的完整架构。有关 template.json 文件的详细信息，请参阅 dotnet 模板化 wiki。有关如何在 Visual Studio 中显示模板的更深入示例和信息，请查看 Sayed Hashimi 创建的资源。

示例：

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

└───mytemplate
    │   console.cs
    │   readme.txt
    │
    └───.template.config
            template.json

template.json 文件如下所示：

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

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

模板本地化

.NET 模板可本地化。如果模板已本地化为与当前区域设置匹配的语言，则其元素以与 CLI 相同的语言显示。创建新模板时，本地化是可选的。

模板上的可本地化元素包括：

名称
作者
DESCRIPTION
符号
- DESCRIPTION
- 显示名称
- 选项参数中选项的说明和显示名称
发布操作
- DESCRIPTION
- 手动说明

本地化文件具有 JSON 格式，每种文化只应存在一个文件。命名约定为： templatestrings.<lang code>.json，其中 lang code 对应于 CultureInfo 选项之一。所有本地化文件都应位于 .template-config\localize 文件夹中。

本地化 JSON 由键值对组成：

键是对要本地化的 template.json 的元素的引用。如果元素是子元素，请使用带 / 分隔符的完整路径。
该值是键给出的元素的本地化字符串。

有关本地化模板的详细信息，请参阅 dotnet 模板化 Wiki 的本地化页面。

示例：

例如，这里是一个包含一些可本地化字段的 template.json 文件：

{
  "$schema": "http://json.schemastore.org/template",
  "author": "Microsoft",
  "classifications": "Config",
  "name": "EditorConfig file",
  "description": "Creates an .editorconfig file for configuring code style preferences.",
  "symbols": {
    "Empty": {
      "type": "parameter",
      "datatype": "bool",
      "defaultValue": "false",
      "displayName": "Empty",
      "description": "Creates empty .editorconfig instead of the defaults for .NET."
    }
  }
}

一些字段将本地化为巴西葡萄牙语。文件名将变为 templatestrings.pt-BR.json 以匹配区域性，如下所示：

{
  "author": "Microsoft",
  "name": "Arquivo EditorConfig",
  "description": "Cria um arquivo .editorconfig para configurar as preferências de estilo de código.",
  "symbols/Empty/displayName": "Vazio",
  "symbols/Empty/description": "Cria .editorconfig vazio em vez dos padrões para .NET."
}

将模板打包到 NuGet 包（nupkg 文件）

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

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

该 <PackageType> 设置已添加并设置为 Template。
该 <PackageVersion> 设置已添加并设置为有效的 NuGet 版本号。
该 <PackageId> 设置已添加并设置为唯一标识符。此标识符用于卸载模板包，NuGet 源用它来注册你的模板包。
应设置泛型元数据设置： <Title>、 <Authors>、 <Description>和 <PackageTags>。
必须设置 <TargetFramework> 设置，即使未使用模板过程生成的二进制文件也必须设置。在下面的示例中，它设置为 netstandard2.0.

模板包以 .nupkg NuGet 包的形式要求所有模板都存储在包内 的内容 文件夹中。 .csproj 文件中需要添加一些设置，以确保生成的 .nupkg 能被安装为模板包：

该 <IncludeContentInPack> 设置被设置为 true 以将任何项目中设为内容的文件包含在 NuGet 包中。
该 <IncludeBuildOutput> 设置设置为 false 从 NuGet 包中排除编译器生成的所有二进制文件。
<ContentTargetFolders> 设置设为 content。这可确保将被设置为内容的文件存储在 NuGet 包的content文件夹中。 NuGet 包中的此文件夹由 dotnet 模板系统分析。

使所有代码文件不被模板项目编译的一个简单的方法是使用 <Compile Remove="**\*" /> 元素内项目文件中的 <ItemGroup> 项。

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

下面是遵循所有这些准则的示例 .csproj 文件。它将模板子文件夹打包到内容包文件夹，并排除正在编译的任何代码文件。

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <PackageType>Template</PackageType>
    <PackageVersion>1.0</PackageVersion>
    <PackageId>AdatumCorporation.Utility.Templates</PackageId>
    <Title>AdatumCorporation Templates</Title>
    <Authors>Me</Authors>
    <Description>Templates to use when creating an application for Adatum Corporation.</Description>
    <PackageTags>dotnet-new;templates;contoso</PackageTags>
    <TargetFramework>netstandard2.0</TargetFramework>

    <IncludeContentInPack>true</IncludeContentInPack>
    <IncludeBuildOutput>false</IncludeBuildOutput>
    <ContentTargetFolders>content</ContentTargetFolders>
  </PropertyGroup>

  <ItemGroup>
    <Content Include="templates\**\*" Exclude="templates\**\bin\**;templates\**\obj\**" />
    <Compile Remove="**\*" />
  </ItemGroup>

</Project>

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

project_folder
│   MyDotnetTemplates.csproj
│
└───templates
    ├───mytemplate1
    │   │   console.cs
    │   │   readme.txt
    │   │
    │   └───.template.config
    │           template.json
    │
    └───mytemplate2
        │   otherfile.cs
        │
        └───.template.config
                template.json

注释

若要确保模板包出现在结果中 dotnet new search ，请将 NuGet 包类型设置为 Template。

安装模板包

使用 dotnet new install 命令安装模板包。

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

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

dotnet new install <NUGET_PACKAGE_ID>

从自定义 NuGet 源安装模板包

提供自定义 NuGet 源（例如 https://api.my-custom-nuget.com/v3/index.json）。

dotnet new install <NUGET_PACKAGE_ID> --nuget-source <SOURCE>

从本地 nupkg 文件安装模板包的具体步骤

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

dotnet new install <PATH_TO_NUPKG_FILE>

从文件系统目录安装模板包

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

dotnet new install <FILE_SYSTEM_DIRECTORY>

获取已安装模板包的列表

卸载命令（不包含任何其他参数）列出了所有已安装的模板包和包含的模板。

dotnet new uninstall

此命令返回类似于以下输出的内容：

Currently installed items:
   Microsoft.Azure.WebJobs.ProjectTemplates
      Version: 4.0.1942
      Details:
         Author: Microsoft
         NuGetSource: https://api.nuget.org/v3/index.json
      Templates:
         Azure Functions (func) C#
         Azure Functions (func) F#
      Uninstall Command:
         dotnet new uninstall Microsoft.Azure.WebJobs.ProjectTemplates
...

之后的第一级项 Currently installed items: 是卸载模板包时使用的标识符。在上一个示例中，提到了 Microsoft.Azure.WebJobs.ProjectTemplates。如果使用文件系统路径安装模板包，则此标识符是 .template.config 文件夹的文件夹路径。列表中仅显示通过 dotnet new install 安装的模板包。不会显示内置于 .NET SDK 的模板包。

卸载模板包

使用 dotnet new uninstall 命令卸载模板包。

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

dotnet new uninstall <NUGET_PACKAGE_ID>

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

dotnet new uninstall <FILE_SYSTEM_DIRECTORY>

使用自定义模板创建项目

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

dotnet new <TEMPLATE>