Создание пользовательского шаблона для команды dotnet newCreate a custom template for dotnet new

В этом учебнике демонстрируется выполнение следующих действий:This tutorial shows you how to:

  • создание базового шаблона на основе существующего проекта или нового проекта консольного приложения;Create a basic template from an existing project or a new console app project.
  • упаковка шаблона для распространения с сайта nuget.org или из локального файла NUPKG;Pack the template for distribution at nuget.org or from a local nupkg file.
  • установка шаблона с сайта nuget.org, из локального файла NUPKG или из локальной файловой системы;Install the template from nuget.org, a local nupkg file, or the local file system.
  • удаление шаблона.Uninstall the template.

Если при изучении руководства вы хотите использовать готовый пример, скачайте его.If you prefer to proceed through the tutorial with a complete sample, download the sample project template. Образец шаблона настроен для распространения посредством NuGet.The sample template is configured for NuGet distribution.

Если вы хотите скачать образец и использовать распространение из файловой системы, выполните указанные ниже действия.If you wish to use the downloaded sample with file system distribution, do the following:

  • Переместите содержимое папки content образца на один уровень вверх в папку GarciaSoftware.ConsoleTemplate.CSharp.Move the contents of the content folder of the sample up one level into the GarciaSoftware.ConsoleTemplate.CSharp folder.
  • Удалите пустую папку content.Delete the empty content folder.
  • Удалите файл NUSPEC.Delete the nuspec file.

Предварительные требованияPrerequisites

Создание шаблона на основе проектаCreate a template from a project

Используйте существующий проект, который компилируется и выполняется, или создайте проект консольного приложения в папке на жестком диске.Use an existing project that you've confirmed compiles and runs, or create a new console app project in a folder on your hard drive. В этом руководстве предполагается, что папка проекта имеет имя GarciaSoftware.ConsoleTemplate.CSharp и хранится в каталоге Documents\Templates в профиле пользователя.This tutorial assumes that the name of the project folder is GarciaSoftware.ConsoleTemplate.CSharp stored at Documents\Templates in the user's profile. Имя шаблона проекта в учебнике имеет формат <Название организации>.<Тип шаблона>.<Язык программирования> , однако вы можете назвать проект и шаблон, как вам нравится.The tutorial project template name is in the format <Company Name>.<Template Type>.<Programming Language>, but you're free to name your project and template anything you wish.

  1. Добавьте в корневой каталог проекта папку с именем .template.config.Add a folder to the root of the project named .template.config.
  2. В папке .template.config создайте файл template.json для настройки шаблона.Inside the .template.config folder, create a template.json file to configure your template. Дополнительные сведения и определения элементов для файла template.json см. в статье Пользовательские шаблоны для команды dotnet new и схеме template.json в хранилище схем JSON.For more information and member definitions for the template.json file, see the Custom templates for dotnet new topic and the template.json schema at the JSON Schema Store.
{
    "$schema": "http://json.schemastore.org/template",
    "author": "Catalina Garcia",
    "classifications": [ "Common", "Console" ],
    "identity": "GarciaSoftware.ConsoleTemplate.CSharp",
    "name": "Garcia Software Console Application",
    "shortName": "garciaconsole"
}

Шаблон готов.The template is finished. На этом этапе возможны два варианта распространения шаблона.At this point, you have two options for template distribution. Чтобы продолжить прохождение учебника, выберите один из них.To continue this tutorial, choose one path or the other:

  1. Распространение посредством NuGet: установите шаблон из пакета NuGet или из локального файла NUPKG, а затем используйте установленный шаблон.NuGet distribution: install the template from NuGet or from the local nupkg file, and use the installed template.
  2. Распространение из файловой системы.File system distribution.

Распространение посредством NuGetUse NuGet Distribution

Упаковка шаблона в пакет NuGetPack the template into a NuGet package

  1. Создайте папку для пакета NuGet.Create a folder for the NuGet package. В этом руководстве используется имя папки GarciaSoftware.ConsoleTemplate.CSharp. Папка создается в каталоге Documents\NuGetTemplates в профиле пользователя.For the tutorial, the folder name GarciaSoftware.ConsoleTemplate.CSharp is used, and the folder is created inside a Documents\NuGetTemplates folder in the user's profile. В новой папке шаблона создайте папку content, в которой будут размещаться файлы проекта.Create a folder named content inside of the new template folder to hold the project files.

  2. Скопируйте содержимое папки проекта вместе с файлом .template.config/template.json помещаются в созданную папку content.Copy the contents of your project folder, together with its .template.config/template.json file, into the content folder you created.

  3. Рядом с папкой content добавьте файл NUSPEC.Next to the content folder, add a nuspec file. Файл NUSPEC представляет собой XML-файл манифеста, описывающий содержимое пакета и управляющий процессом создания пакета NuGet.The nuspec file is an XML manifest file that describes a package's contents and drives the process of creating the NuGet package.

    Структура каталогов пакета NuGet

  4. Внутри элемента <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 Pre-release versions.

    Полную схему файла NUSPEC см. в справочнике по NUSPEC.See the .nuspec reference for the complete nuspec file schema.

    Файл NUSPEC для учебника называется GarciaSoftware.ConsoleTemplate.CSharp.nuspec и имеет следующее содержимое:The nuspec file for the tutorial is named GarciaSoftware.ConsoleTemplate.CSharp.nuspec and contains the following content:

    <?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>
    
  5. Создайте пакет с помощью команды nuget pack <PATH_TO_NUSPEC_FILE>.Create the package using the nuget pack <PATH_TO_NUSPEC_FILE> command. В приведенной ниже команде предполагается, что папка, содержащая ресурсы NuGet, находится в каталоге C:\Users\<USER>\Documents\Templates\GarciaSoftware.ConsoleTemplate.CSharp.The following command assumes that the folder that holds the NuGet assets is at C:\Users\<USER>\Documents\Templates\GarciaSoftware.ConsoleTemplate.CSharp. Однако где бы ни находилась эта папка в вашей системе, команда nuget pack принимает путь к файлу NUSPEC:But wherever you place the folder on your system, the nuget pack command accepts the path to the nuspec file:

    nuget pack C:\Users\<USER>\Documents\NuGetTemplates\GarciaSoftware.ConsoleTemplate.CSharp\GarciaSoftware.ConsoleTemplate.CSharp.nuspec
    

Публикация пакета на сайте nuget.orgPublishing the package to nuget.org

Чтобы опубликовать пакет NuGet, выполните инструкции, приведенные в статье Создание и публикация пакета.To publish a NuGet package, follow the instructions in the Create and publish a package topic. Однако мы не рекомендуем публиковать шаблон из учебника в NuGet, так как после публикации его нельзя будет удалить. Вы сможете только удалить его из списка.However, we recommend that you don't publish the tutorial template to NuGet as it can never be deleted once published, only delisted. Теперь, когда имеется пакет NuGet в виде файла NUPKG, мы рекомендуем вам выполнить приведенные ниже инструкции, чтобы установить шаблон непосредственно из локального файла NUPKG.Now that you have the NuGet package in the form of a nupkg file, we suggest that you follow the instructions below to install the template directly from the local nupkg file.

Установка шаблона из пакета NuGetInstall the template from a NuGet package

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

Чтобы установить шаблон из созданного файла NUPKG, используйте команду dotnet new с параметром -i|--install и укажите путь к файлу NUPKG.To install the template from the nupkg file that you produced, use the dotnet new command with the -i|--install option and provide the path to the nupkg file:

dotnet new -i C:\Users\<USER>\GarciaSoftware.ConsoleTemplate.CSharp.1.0.0.nupkg

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

Чтобы установить шаблон из пакета NuGet, хранящегося на сайте nuget.org, используйте команду dotnet new с параметром -i|--install и укажите имя пакета NuGet.If you wish to install a template from a NuGet package stored at nuget.org, use the dotnet new command with the -i|--install option and supply the name of the NuGet package:

dotnet new -i GarciaSoftware.ConsoleTemplate.CSharp

Примечание

Этот пример приведен только в качестве демонстрации.The example is for demonstration purposes only. На сайте nuget.org нет пакета NuGet GarciaSoftware.ConsoleTemplate.CSharp, и мы не рекомендуем публиковать тестовые шаблоны и использовать их из NuGet.There isn't a GarciaSoftware.ConsoleTemplate.CSharp NuGet package at nuget.org, and we don't recommend that you publish and consume test templates from NuGet. При выполнении этой команды шаблон не устанавливается.If you run the command, no template is installed. Однако вы можете установить шаблон, который не опубликован на сайте nuget.org, напрямую сославшись на файл NUPKG в локальной файловой системе, как описано в предыдущем разделе Установка шаблона из локального файла NUPKG.However, you can install a template that hasn't been published to nuget.org by referencing the nupkg file directly on your local file system as shown in the previous section Install the template from the local nupkg file.

Чтобы ознакомиться с рабочим примером установки шаблона из пакета на сайте nuget.org, воспользуйтесь шаблоном NUnit 3 для dotnet-new.If you'd like a live example of how to install a template from a package at nuget.org, you can use the NUnit 3 template for dotnet-new. Этот шаблон создает проект для использования модульного тестирования NUnit.This template sets up a project to use NUnit unit testing. Для его установки используйте следующую команду:Use the following command to install it:

dotnet new -i NUnit3.DotNetNew.Template

Если вывести список шаблонов с помощью команды dotnet new -l, в нем будет присутствовать элемент NUnit 3 Test Project с коротким именем nunit.When you list the templates with dotnet new -l, you see the NUnit 3 Test Project with a short name of nunit in the template list. Шаблон готов к использованию в следующем разделе.You're ready to use the template in the next section.

Окно консоли с шаблоном NUnit и другими шаблонами

Создание проекта на основе шаблонаCreate a project from the template

После установки шаблона из NuGet используйте его, выполнив команду dotnet new <TEMPLATE> из каталога, в котором должны размещаться выходные данные модуля шаблонов (если вы не применяете параметр -o|--output для указания определенного каталога).After the template is installed from NuGet, use the template by executing the dotnet new <TEMPLATE> command from the directory where you want to the template engine's output placed (unless you're using the -o|--output option to specify a specific directory). Дополнительные сведения см. в разделе Параметры статьи, посвященной команде dotnet new.For more information, see dotnet new Options. Укажите короткое имя шаблона непосредственно в команде dotnet new.Supply the template's short name directly to the dotnet new command. Чтобы создать проект на основе шаблона NUnit, выполните следующую команду:To create a project from the NUnit template, run the following command:

dotnet new nunit

В консоли показано, что проект создан и что его пакеты восстановлены.The console shows that the project is created and that the project's packages are restored. После выполнения команды проект готов к использованию.After the command is run, the project is ready for use.

Окно консоли с результатом выполнения команды dotnet new nunit и восстановленными зависимостями проекта

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

dotnet new -u GarciaSoftware.ConsoleTemplate.CSharp

Примечание

Этот пример приведен только в качестве демонстрации.The example is for demonstration purposes only. На сайте nuget.org нет пакета NuGet GarciaSoftware.ConsoleTemplate.CSharp, и он не устанавливается с пакетом SDK для .NET Core.There isn't a GarciaSoftware.ConsoleTemplate.CSharp NuGet package at nuget.org or installed with the .NET Core SDK. При выполнении команды пакет или шаблон не удаляется и возникает следующее исключение:If you run the command, no package/template is uninstalled and you receive the following exception:

Не удалось найти объект для удаления с именем GarciaSoftware.ConsoleTemplate.CSharp.Could not find something to uninstall called 'GarciaSoftware.ConsoleTemplate.CSharp'.

Если вы установили шаблон NUnit 3 для dotnet-new и хотите удалить его, используйте следующую команду:If you installed the NUnit 3 template for dotnet-new and wish to uninstall it, use the following command:

dotnet new -u NUnit3.DotNetNew.Template

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

Если необходимо удалить шаблон, не пытайтесь использовать путь к файлу NUPKG.When you wish 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 GarciaSoftware.ConsoleTemplate.CSharp.1.0.0

Распространение из файловой системыUse file system distribution

Для распространения шаблона поместите папку шаблона проекта в месте, которое доступно пользователям сети.To distribute the template, place the project template folder in a location accessible to users on your network. Используйте команду dotnet new с параметром -i|--install и укажите путь к папке шаблона (папке проекта, содержащей проект и папку .template.config).Use the dotnet new command with the -i|--install option and specify the path to the template folder (the project folder containing the project and the .template.config folder).

В этом учебнике предполагается, что шаблон проекта находится в папке Documents/Templates в профиле пользователя.The tutorial assumes the project template is stored in the Documents/Templates folder of the user's profile. Установите шаблон из этого расположения с помощью следующей команды, заменив <ПОЛЬЗОВАТЕЛЬ> на имя профиля пользователя:From that location, install the template with the following command replacing <USER> with the user's profile name:

dotnet new -i C:\Users\<USER>\Documents\Templates\GarciaSoftware.ConsoleTemplate.CSharp

Создание проекта на основе шаблонаCreate a project from the template

После установки шаблона из файловой системы используйте его, выполнив команду dotnet new <TEMPLATE> из каталога, в котором должны размещаться выходные данные модуля шаблонов (если вы не применяете параметр -o|--output для указания определенного каталога).After the template is installed from the file system, use the template by executing the dotnet new <TEMPLATE> command from the directory where you want to the template engine's output placed (unless you're using the -o|--output option to specify a specific directory). Дополнительные сведения см. в разделе Параметры статьи, посвященной команде dotnet new.For more information, see dotnet new Options. Укажите короткое имя шаблона непосредственно в команде dotnet new.Supply the template's short name directly to the dotnet new command.

Из новой папки проекта, созданной в каталоге C:\Users\<USER>\Documents\Projects\MyConsoleApp, создайте проект на основе шаблона garciaconsole:From a new project folder created at C:\Users\<USER>\Documents\Projects\MyConsoleApp, create a project from the garciaconsole template:

dotnet new garciaconsole

Удаление шаблонаUninstall the template

Если вы создали шаблон в локальной файловой системе в каталоге C:\Users\<USER>\Documents\Templates\GarciaSoftware.ConsoleTemplate.CSharp, для его удаления укажите параметр -u|--uninstall и путь к папке шаблона:If you created the template on your local file system at C:\Users\<USER>\Documents\Templates\GarciaSoftware.ConsoleTemplate.CSharp, uninstall it with the -u|--uninstall switch and the path to the template folder:

dotnet new -u C:\Users\<USER>\Documents\Templates\GarciaSoftware.ConsoleTemplate.CSharp

Примечание

Чтобы удалить шаблон из локальной файловой системы, вам необходимо указать полный путь.To uninstall the template from your local file system, you need to fully qualify the path. Например, C:\Users\<USER>\Documents\Templates\GarciaSoftware.ConsoleTemplate.CSharp будет работать, а ./GarciaSoftware.ConsoleTemplate.CSharp из содержащей папки — нет.For example, C:\Users\<USER>\Documents\Templates\GarciaSoftware.ConsoleTemplate.CSharp will work, but ./GarciaSoftware.ConsoleTemplate.CSharp from the containing folder will not. Кроме того, путь к шаблону не должен содержать конечную косую черту закрытия каталога.Additionally, do not include a final terminating directory slash on your template path.

См. такжеSee also