本教程介绍了如何:
- 通过现有项目或新控制台应用程序项目创建基本模板。
- 从 nuget.org 或本地 nupkg 文件打包模板以供分发。
- 从 nuget.org、本地 nupkg 文件或本地文件系统安装模板。
- 卸载模板。
若要通过完整示例继续学习本教程,请下载示例项目模板。 示例模板针对 NuGet 分发进行了配置。
若要将下载的示例与文件系统分发相结合,请按照以下步骤操作:
- 将示例中 content 文件夹的内容移到上一级 GarciaSoftware.ConsoleTemplate.CSharp 文件夹中。
- 删除空的 content 文件夹。
- 删除 nuspec 文件。
系统必备
- 安装 .NET Core 2.0 SDK 或更高版本。
- 阅读参考主题 dotnet new 自定义模板。
通过项目创建模板
使用已确认的可以编译和运行的现有项目,或在硬盘上的文件夹中新建一个控制台应用项目。 本教程假定项目文件夹名为 GarciaSoftware.ConsoleTemplate.CSharp,并存储在用户文件夹下的 Documents\Templates下。 本教程的项目模板名称采用格式“<公司名称>.<模板类型>.<编程语言>”,但也可以根据自己的意愿随意命名项目和模板。
- 向项目根目录下添加一个文件夹,命名为 .template.config。
- 在 .template.config 文件夹下,创建一个 template.json 文件来配置您的模板。 有关 template.json 文件的详细信息和成员定义,请参阅 dotnet new 自定义模板主题和 JSON 架构存储中的 template.json 架构。
{
"$schema": "http://json.schemastore.org/template",
"author": "Catalina Garcia",
"classifications": [ "Common", "Console" ],
"identity": "GarciaSoftware.ConsoleTemplate.CSharp",
"name": "Garcia Software Console Application",
"shortName": "garciaconsole"
}
模板已完成。 此时,可通过两种方式分发模板。 若要继续阅读本教程,请选择下面两种路径之一:
使用 NuGet 分发
将模板打包到 NuGet 包中
-
为 NuGet 包创建文件夹。 在本教程中,使用的文件夹名为 GarciaSoftware.ConsoleTemplate.CSharp,该文件夹在用户文件夹的 Documents\NuGetTemplates 下。 在该文件夹下,创建名为 content 的文件夹,以保存项目文件。
-
将项目文件夹的内容连同 .template.config/template.json 文件一起复制到创建的 content 文件夹中。
-
在 content 文件夹旁边,添加 nuspec 文件。 nuspec 文件是 XML 清单文件,用于描述包内容,并驱动创建 NuGet 包的过程。
-
在 nuspec文件的 <packageTypes> 元素中,添加 一个 <packageType> 元素,它带有一个
name
属性,其值为Template
。 content 文件夹和 nuspec 文件应位于同一目录。 下表列出了将模板生成为 NuGet 包至少所需的 nuspec 文件元素。元素 类型 说明 <authors> 字符串 包创建者的逗号分隔列表,与 nuget.org 上的配置文件名称一致。创建者显示在 nuget.org 上的 NuGet 库中,用于交叉引用同一创建者的包。 <description> 字符串 用于 UI 显示的包的详细说明。 <id> 字符串 不区分大小写的包标识符,在 nuget.org 或包驻留的任意库中必须是唯一的。 ID 不得包含空格或对 URL 无效的字符,通常遵循 .NET 命名空间规则。 有关指南,请参阅选择唯一包标识符并设置版本号。 <packageType> 字符串 将此元素置于 <metadata> 元素之间的 <packageTypes> 元素内。 将 <packageType> 元素的 name
属性设置为Template
。<version> 字符串 遵循 major.minor.patch 模式的包版本。 版本号可能包括预发布后缀,如预发布版本中所述。 有关完整的 nuspec 文件架构,请参阅 .nuspec 参考。
在本教程中,nuspec 文件命名为 GarciaSoftware.ConsoleTemplate.CSharp.nuspec,包含以下内容:
<?xml version="1.0" encoding="utf-8"?> <package xmlns="http://schemas.microsoft.com/packaging/2012/06/nuspec.xsd"> <metadata> <id>GarciaSoftware.ConsoleTemplate.CSharp</id> <version>1.0.0</version> <description> Creates the Garcia Software console app. </description> <authors>Catalina Garcia</authors> <packageTypes> <packageType name="Template" /> </packageTypes> </metadata> </package>
-
使用
nuget pack <PATH_TO_NUSPEC_FILE>
命令创建包。 以下命令假定包含 NuGet 资产的文件夹位于 C:\Users\<USER>\Documents\Templates\GarciaSoftware.ConsoleTemplate.CSharp。 不过,无论将文件夹放置在系统上的什么位置,nuget pack
命令都接受 nuspec 文件路径:nuget pack C:\Users\<USER>\Documents\NuGetTemplates\GarciaSoftware.ConsoleTemplate.CSharp\GarciaSoftware.ConsoleTemplate.CSharp.nuspec
将包发布到 nuget.org
若要发布 NuGet 包,请按照创建和发布包主题中的说明操作。 不过,不建议将本教程的模板发布到 NuGet,因为一旦发布,便永远无法删除,只能从列表去除。 既然已拥有 nupkg 文件形式的 NuGet 包,建议按照下面的说明操作,直接从本地 nupkg 文件安装模板。
从 NuGet 包安装模板
从本地 nupkg 文件安装模板
若要从生成的 nupkg 文件安装模板,请结合使用 dotnet new
命令和 -i|--install
选项,并提供 nupkg 文件路径:
dotnet new -i C:\Users\<USER>\GarciaSoftware.ConsoleTemplate.CSharp.1.0.0.nupkg
从 nuget.org 中存储的 NuGet 包安装模板
若要从 nuget.org 中存储的 NuGet 包安装模板,请结合使用 dotnet new
命令和 -i|--install
选项,并提供 NuGet 包名称:
dotnet new -i GarciaSoftware.ConsoleTemplate.CSharp
备注
示例代码只为了方便本文演示。 如果 nuget.org 中没有
GarciaSoftware.ConsoleTemplate.CSharp
NuGet 包,不建议发布并从 NuGet 使用测试模板。 如果运行此命令,不会安装任何模板。 不过,可以安装尚未发布到 nuget.org 的模板,具体方法是直接在本地文件系统上引用 nupkg 文件,如前一章节从本地 nupkg 文件安装模板所述。
如果需要获取有关如何从 nuget.org 中的包安装模板的实际示例,可以使用 dotnet-new 的 NUnit 3 模板。 此模板将项目设置为使用 NUnit 单元测试。 运行以下命令安装此模板:
dotnet new -i NUnit3.DotNetNew.Template
使用 dotnet new -l
列出模板时,模板列表中会列出短名称为“nunit”的“NUnit 3 测试项目”。 可以在下一部分中使用此模板了。
通过模板创建项目
从 NuGet 安装模板后,在模板引擎要放置输出的目录(除非使用 -o|--output
选项指定特定的目录)执行 dotnet new <TEMPLATE>
命令,即可使用模板。 有关详细信息,请参阅 dotnet new
选项。直接向 dotnet new
命令提供模板的短名称。 若要通过 NUnit 模板创建项目,请运行以下命令:
dotnet new nunit
控制台显示项目已创建,且项目包已还原。 运行此命令后,项目便可供使用。
从 nuget.org 中存储的 NuGet 包卸载模板的具体步骤
dotnet new -u GarciaSoftware.ConsoleTemplate.CSharp
备注
示例代码只为了方便本文演示。
GarciaSoftware.ConsoleTemplate.CSharp
NuGet 包没有存储到 nuget.org 或与 .NET Core SDK 一起安装。 如果运行此命令,不会卸载任何包/模板,并会看到以下异常消息:找不到要卸载的“GarciaSoftware.ConsoleTemplate.CSharp”包/模板。
若要卸载已安装的 dotnet-new 的 NUnit 3 模板,请运行以下命令:
dotnet new -u NUnit3.DotNetNew.Template
从本地 nupkg 文件卸载模板
若要卸载模板,请勿尝试使用 nupkg 文件路径。 使用 dotnet new -u <PATH_TO_NUPKG_FILE>
卸载模板会失败。 按 id
引用包:
dotnet new -u GarciaSoftware.ConsoleTemplate.CSharp.1.0.0
使用文件系统分发
若要分发模板,请确保用户可以在网络上访问项目模板文件夹的位置。 结合使用 dotnet new
命令和 -i|--install
选项,并指定模板文件夹路径(包含项目和 .template.config 文件夹的项目文件夹)。
本教程假定项目模板存储在用户文件夹下的 Documents/Templates 文件夹内。 从这个位置,使用以下命令安装模板,只将 <USER> 替换为实际的用户名:
dotnet new -i C:\Users\<USER>\Documents\Templates\GarciaSoftware.ConsoleTemplate.CSharp
通过模板创建项目
从文件系统安装模板后,在要放置模板引擎输出的目录(除非使用 -o|--output
选项指定特定的目录)执行 dotnet new <TEMPLATE>
命令,即可使用模板。 有关详细信息,请参阅 dotnet new
选项。直接向 dotnet new
命令提供模板的短名称。
从 C:\Users\<USER>\Documents\Projects\MyConsoleApp 处创建的新项目文件夹,通过 garciaconsole
模板创建项目:
dotnet new garciaconsole
卸载模板
如果在本地文件系统中的 C:\Users\<USER>\Documents\Templates\GarciaSoftware.ConsoleTemplate.CSharp 处创建模板,请使用 -u|--uninstall
开关和模板文件夹路径卸载模板:
dotnet new -u C:\Users\<USER>\Documents\Templates\GarciaSoftware.ConsoleTemplate.CSharp
备注
若要从本地文件系统卸载模板,需要完全限定路径。 例如,C:\Users\<USER>\Documents\Templates\GarciaSoftware.ConsoleTemplate.CSharp 有效,而 ./GarciaSoftware.ConsoleTemplate.CSharp 无效。 此外,模板路径中不要包含最后的目录斜杠。