Пользовательские шаблоны для команды dotnet newCustom templates for dotnet new

В состав пакета SDK для .NET Core входит множество готовых шаблонов, предназначенных для использования с командой dotnet new.The .NET Core SDK comes with many templates pre-installed to use with the dotnet new command. Начиная с версии .NET Core 2.0, можно создавать собственные шаблоны для проектов любого типа, например приложений, служб, средств или библиотек классов.Starting with .NET Core 2.0, you can create your own custom templates for any type of project, such as an app, service, tool, or class library. Можно также создать шаблон, формирующий один или несколько отдельных файлов, например файл конфигурации.You can even create a template that outputs one or more independent files, such as a configuration file.

Устанавливать пользовательские шаблоны из пакета NuGet можно в любом веб-канале NuGet, ссылаясь на файл NUPKG NuGet напрямую или указывая каталог в файловой системе, который содержит шаблон.You can install custom templates from a NuGet package on any NuGet feed, by referencing a NuGet nupkg file directly, or by specifying a file system directory that contains the template. Модуль шаблонов предоставляет возможности, которые позволяют заменять значения, включать и исключать файлы или области файлов, а также выполнять пользовательские операции обработки при использовании шаблона.The template engine offers features that allow you to replace values, include and exclude files and regions of files, and execute custom processing operations when your template is used.

Модуль шаблонов имеет открытый код. Репозиторий кода в Интернете — dotnet/templating в GitHub.The template engine is open source, and the online code repository is at dotnet/templating on GitHub. Образцы шаблонов можно найти в репозитории dotnet/dotnet-template-samples.Visit the dotnet/dotnet-template-samples repo for samples of templates. Дополнительные шаблоны, в том числе шаблоны от сторонних разработчиков, можно найти на странице Доступные шаблоны для dotnet new в GitHub.More templates, including templates from third parties, are found at Available templates for dotnet new on GitHub. Дополнительные сведения о создании и использовании пользовательских шаблонов см. в записи блога Создание собственных шаблонов для команды dotnet new и на вики-сайте, посвященном репозиторию dotnet/templating в GitHub.For more information about creating and using custom templates, see How to create your own templates for dotnet new and the dotnet/templating GitHub repo Wiki.

Пошаговое руководство по созданию шаблона см. в учебнике Создание пользовательского шаблона для команды dotnet new.To follow a walkthrough and create a template, see the Create a custom template for dotnet new tutorial.

Параметр ConfigurationConfiguration

Шаблон состоит из следующих компонентов:A template is composed of the following components:

  • исходные файлы и папки;Source files and folders
  • файл конфигурации (template.json).A configuration file (template.json)

Исходные файлы и папкиSource files and folders

К исходным файлам и папкам относятся все файлы и папки, которые должны использоваться модулем шаблонов при выполнении команды dotnet new <TEMPLATE>.The source files and folders include whatever files and folders you want the template engine to use when the dotnet new <TEMPLATE> command is executed. Модуль шаблонов предполагает использование запускаемых проектов в качестве исходного кода для создания проектов.The template engine is designed to use runnable projects as source code to produce projects. Это дает ряд преимуществ.This has several benefits:

  • Модуль шаблонов не требует внедрения специальных токенов в исходный код проекта.The template engine doesn't require you to inject special tokens into your project's source code.
  • Файлы кода не являются особыми файлами и не требуют каких-либо изменений для работы с модулем шаблонов.The code files aren't special files or modified in any way to work with the template engine. Поэтому для работы с содержимым шаблонов можно использовать те же средства, которые вы обычно используете при работе с проектами.So, the tools you normally use when working with projects also work with template content.
  • Сборка, выполнение и отладка проектов шаблонов осуществляется так же, как и в случае с любыми другими проектами.You build, run, and debug your template projects just like you do for any of your other projects.
  • Вы можете быстро создать шаблон на основе существующего проекта, просто добавив файл конфигурации template.json в проект.You can quickly create a template from an existing project just by adding a template.json configuration file to the project.

Файлы и папки, которые могут храниться в шаблоне, не ограничены формальными типами проектов .NET, такими как решения .NET Core или .NET Framework.Files and folders stored in the template aren't limited to formal .NET project types, such as .NET Core or .NET Framework solutions. Исходные файлы и папки могут включать в себя любое содержимое, которое требуется создавать при использовании шаблона, даже если модуль шаблонов создает только один файл в качестве выходного, например файл конфигурации или файл решения.Source files and folders may consist of any content that you wish to create when the template is used, even if the template engine produces just one file for its output, such as a configuration file or a solution file. Например, можно создать шаблон, который содержит исходный файл web.config и создает измененный файл web.config для проектов, в которых используется этот шаблон.For example, you can create a template that contains a web.config source file and creates a modified web.config file for projects where the template is used. Изменения в исходные файлы вносятся на основе логики и параметров, указанных в файле конфигурации template.json, а также значений, предоставляемых пользователем и передаваемых в качестве параметров в команду dotnet new <TEMPLATE>.The modifications to source files are based on logic and settings you've provided in the template.json configuration file along with values provided by the user passed as options to the dotnet new <TEMPLATE> command.

template.jsontemplate.json

Файл template.json размещается в папке .template.config в корневом каталоге шаблона.The template.json file is placed in a .template.config folder in the root directory of the template. Он предоставляет сведения о конфигурации модулю шаблонов.The file provides configuration information to the template engine. В приведенной ниже таблице приведены элементы конфигурации, которые необходимы и достаточны для создания работающего шаблона.The minimum configuration requires the members shown in the following table, which is sufficient to create a functional template.

ЧленMember ТипType ОписаниеDescription
$schema URIURI Схема JSON для файла template.json.The JSON schema for the template.json file. Редакторы, поддерживающие схемы JSON, обеспечивают возможности редактирования JSON при указании схемы.Editors that support JSON schemas enable JSON-editing features when the schema is specified. Например, в Visual Studio Code требуется, чтобы этот элемент включал поддержку IntelliSense.For example, Visual Studio Code requires this member to enable IntelliSense. Используйте значение http://json.schemastore.org/template.Use a value of http://json.schemastore.org/template.
author stringstring Автор шаблона.The author of the template.
classifications array(string)array(string) Ноль или более характеристик шаблона, по которым пользователь может найти его.Zero or more characteristics of the template that a user might use to find the template when searching for it. Если шаблон присутствует в списке шаблонов, созданных с помощью команды dotnet new -l|--list, классификации также приводятся в столбце Теги.The classifications also appear in the Tags column when it appears in a list of templates produced by using the dotnet new -l|--list command.
identity stringstring Уникальное имя шаблона.A unique name for this template.
name stringstring Имя шаблона, которое видят пользователи.The name for the template that users should see.
shortName stringstring Сокращение по умолчанию для выбора шаблона, которое используется во всех средах, где имя шаблона указывается пользователем, а не выбирается в графическом пользовательском интерфейсе.A default shorthand for selecting the template that applies to environments where the template name is specified by the user, not selected via a GUI. Например, короткое имя полезно при использовании шаблонов из командной строки с помощью команд CLI.For example, the short name is useful when using templates from a command prompt with CLI commands.

ПримерExample:

{
  "$schema": "http://json.schemastore.org/template",
  "author": "Catalina Garcia",
  "classifications": [ "Common", "Console" ],
  "identity": "GarciaSoftware.ConsoleTemplate.CSharp",
  "name": "Garcia Software Console Application",
  "shortName": "garciaconsole"
}

Полная схема файла template.json находится в хранилище схем JSON.The full schema for the template.json file is found at the JSON Schema Store.

Шаблоны .NET по умолчанию.NET default templates

При установке пакета SDK для .NET Core вы получаете более десяти встроенных шаблонов для создания проектов и файлов, включая консольные приложения, библиотеки классов, проекты модульных тестов, приложения ASP.NET Core (в том числе проекты Angular и React) и файлы конфигурации.When you install the .NET Core SDK, you receive over a dozen built-in templates for creating projects and files, including console apps, class libraries, unit test projects, ASP.NET Core apps (including Angular and React projects), and configuration files. Чтобы получить список встроенных шаблонов, выполните команду dotnet new с параметром -l|--list.To list the built-in templates, execute the dotnet new command with the -l|--list option:

dotnet new -l

Упаковка шаблона в пакет NuGet (файл NUPKG)Packing a template into a NuGet package (nupkg file)

В настоящее время пользовательский шаблон упаковывается в Windows с помощью nuget.exe (а не команды dotnet pack).Currently, a custom template is packed on Windows with nuget.exe (not dotnet pack). Для кроссплатформенной упаковки рекомендуется использовать NuGetizer 3000.For cross-platform packaging, consider using NuGetizer 3000.

Содержимое папки проекта вместе с файлом .template.config/template.json помещаются в папку content.The contents of the project folder, together with its .template.config/template.json file, are placed into a folder named content. Рядом с папкой content добавьте файл NUSPEC, который представляет собой XML-файл манифеста, описывающий содержимое пакета и управляющий процессом создания пакета NuGet.Next to the content folder, add a nuspec file, which is an XML manifest file that describes a package's contents and drives the process of creating the NuGet package. Внутри элемента <packageTypes> в файле NUSPEC добавьте элемент <packageType> с атрибутом name, имеющим значение Template.Inside of a <packageTypes> element in the nuspec file, include a <packageType> element with a name attribute value of Template. Папка content и файл NUSPEC должны находиться в одном каталоге.Both the content folder and the nuspec file should reside in the same directory. В таблице ниже приведен минимальный набор элементов файла NUSPEC, необходимых для создания шаблона как пакета NuGet.The table shows the minimum nuspec file elements required to produce a template as a NuGet package.

ЭлементElement ТипType ОписаниеDescription
<authors><authors> stringstring Разделенный запятыми список авторов пакетов, совпадающих с именами профилей на сайте nuget.org. Авторы отображаются в коллекции NuGet на сайте nuget.org и используются для перекрестных ссылок на пакеты тех же авторов.A comma-separated list of packages authors, matching the profile names on nuget.org. Authors are displayed in the NuGet Gallery on nuget.org and are used to cross-reference packages by the same authors.
<description><description> stringstring Подробное описание пакета для отображения пользовательского интерфейса.A long description of the package for UI display.
<id><id> stringstring Идентификатор пакета без учета регистра, который должен быть уникальным в пределах сайта nuget.org или иной коллекции, в которой будет находиться пакет.The case-insensitive package identifier, which must be unique across nuget.org or whatever gallery the package will reside in. Идентификаторы не должны содержать пробелов или символов, которые недопустимы в URL-адресах, и в них должны соблюдаться общие правила касательно пространств имен .NET.IDs may not contain spaces or characters that are not valid for a URL and generally follow .NET namespace rules. Инструкции см. в разделе Выбор уникального идентификатора пакета и задание номера версии.See Choosing a unique package identifier and setting the version number for guidance.
<packageType><packageType> stringstring Поместите этот элемент внутри элемента <packageTypes> среди элементов <metadata> .Place this element inside a <packageTypes> element among the <metadata> elements. Присвойте атрибуту name элемента <packageType> значение Template.Set the name attribute of the <packageType> element to Template.
<version><version> stringstring Версия пакета, указываемая согласно шаблону основной_номер.дополнительный_номер.исправление.The version of the package, following the major.minor.patch pattern. Номер версии может включать в себя суффикс предварительной версии, как описано в разделе, посвященном предварительным версиям.Version numbers may include a pre-release suffix as described in the Pre-release versions topic.

Полную схему файла NUSPEC см. в справочнике по NUSPEC.See the .nuspec reference for the complete nuspec file schema. Пример файла NUSPEC для шаблона приведен в учебнике по созданию пользовательского шаблона для команды dotnet new.An example nuspec file for a template appears in the Create a custom template for dotnet new tutorial.

Создайте пакет с помощью команды nuget pack <PATH_TO_NUSPEC_FILE>.Create a package using the nuget pack <PATH_TO_NUSPEC_FILE> command.

Установка шаблонаInstalling a template

Установите пользовательский шаблон из пакета NuGet в любом веб-канале NuGet, сославшись на файл NUPKG NuGet напрямую или указав каталог в файловой системе, который содержит конфигурацию шаблона.Install a custom template from a NuGet package on any NuGet feed by referencing a nupkg file directly or by specifying a file system directory that contains a templating configuration. Используйте параметр -i|--install с командой dotnet new.Use the -i|--install option with the dotnet new command.

Установка шаблона из пакета NuGet, хранящегося на сайте nuget.orgTo install a template from a NuGet package stored at nuget.org

dotnet new -i <NUGET_PACKAGE_ID>

Установка шаблона из локального файла NUPKGTo install a template from a local nupkg file

dotnet new -i <PATH_TO_NUPKG_FILE>

Установка шаблона из каталога в файловой системеTo install a template from a file system directory

FILE_SYSTEM_DIRECTORY — это папка проекта, содержащая проект и папку .template.config.The FILE_SYSTEM_DIRECTORY is the project folder containing the project and the .template.config folder:

dotnet new -i <FILE_SYSTEM_DIRECTORY>

Удаление шаблонаUninstalling a template

Удалите пользовательский шаблон, сославшись на пакет NuGet по id или указав каталог в файловой системе, который содержит конфигурацию шаблона.Uninstall a custom template by referencing a NuGet package by its id or by specifying a file system directory that contains a templating configuration. Используйте параметр установки -u|--uninstall с командой dotnet new.Use the -u|--uninstall install option with the dotnet new command.

Удаление шаблона из пакета NuGet, хранящегося на сайте nuget.orgTo uninstall a template from a NuGet package stored at nuget.org

dotnet new -u <NUGET_PACKAGE_ID>

Удаление шаблона из локального файла NUPKGTo uninstall a template from a local nupkg file

Чтобы удалить шаблон, не пытайтесь использовать путь к файлу NUPKG.To uninstall the template, don't attempt to use the path to the nupkg file. Попытка удалить шаблон с помощью команды dotnet new -u <PATH_TO_NUPKG_FILE> завершится сбоем.Attempting to uninstall a template using dotnet new -u <PATH_TO_NUPKG_FILE> fails. Ссылайтесь на пакет по id.Reference the package by its id:

dotnet new -u <NUGET_PACKAGE_ID>

Удаление шаблона из каталога в файловой системеTo uninstall a template from a file system directory

FILE_SYSTEM_DIRECTORY — это папка проекта, содержащая проект и папку .template.config.The FILE_SYSTEM_DIRECTORY is the project folder containing the project and the .template.config folder. Нужно предоставить абсолютный путь.The path provided needs to be the absolute path. Попытка удалить шаблон с помощью команды относительного пути завершится сбоем.Attempting to uninstall a template using a relative path fails. Дополнительные сведения см. в статье dotnet new.For more information, see the dotnet new article.

dotnet new -u <FILE_SYSTEM_DIRECTORY>

Создание проекта с помощью пользовательского шаблонаCreate a project using a custom template

После установки шаблона для его использования выполните команду dotnet new <TEMPLATE> так же, как и в случае с любым другим предустановленным шаблоном.After a template is installed, use the template by executing the dotnet new <TEMPLATE> command as you would with any other pre-installed template. Кроме того, можно указать параметры для команды dotnet new, в том числе относящиеся к шаблону параметры, заданные в настройках шаблона.You can also specify options to the dotnet new command, including template specific options you configured in the template settings. Укажите короткое имя шаблона непосредственно в команде.Supply the template's short name directly to the command:

dotnet new <TEMPLATE>

См. такжеSee also