.NET шаблоны для авторов

В качестве автора шаблона вы создаете .NET шаблоны — схемы, которые создают проекты, файлы или другие ресурсы из предопределенной структуры. При запуске dotnet new <shortName>пользователей подсистема шаблонов .NET считывает шаблон и создает выходные данные в текущем каталоге. в диалоговом окне создания проекта Visual Studio также используется подсистема шаблонов .NET для шаблонов проектов .NET, поэтому шаблоны, созданные для работы с CLI, также используются в Visual Studio.

Пакет SDK .NET поставляется со встроенными шаблонами для распространенных начальных точек, таких как консольные приложения, библиотеки классов и проекты ASP.NET. Помимо встроенных шаблонов, вы можете создавать собственные шаблоны и распространять их в виде пакетов NuGet.

Эта статья содержит ссылку для авторов шаблонов. В ней описывается структура, настройка и распределение шаблонов. Пошаговые инструкции по созданию и пакету шаблонов см. в разделе "Связанное содержимое ".

Типы шаблонов

Модуль шаблонов .NET поддерживает три типа шаблонов: шаблоны элементов, шаблоны проектов и шаблоны решений.

• Шаблоны элементов создают один или несколько файлов, таких как файл кода, файл конфигурации или другой ресурс, без создания всего проекта вокруг них. Например, шаблон элемента может создать файл класса, который добавляет набор методов расширения или файл конфигурации JSON, который соответствует стандартному макету, который используется командой. Сведения о создании шаблона элемента см. в руководстве по созданию шаблона элемента.

• Шаблоны Project создают полную структуру project. Например, встроенный шаблон проекта консоли создает .csproj файл, Program.cs файл и любые другие файлы, составляющие проект. Создайте шаблон проекта, если вы хотите предоставить пользователям полную отправную точку проекта, а не отдельные файлы. Сведения о создании шаблона проекта см. в руководстве по созданию шаблона проекта.

• Шаблоны решений создают решение с одним или несколькими проектами. Например, шаблон решения может создать проект API, связанный с тестируемым проектом на одном шаге.

При создании собственного шаблона вы объявляете его тип с помощью tags.type поля в template.json файле конфигурации. Допустимые значения: "project", "item"и "solution". Эти значения позволяют пользователям фильтровать результаты при поиске шаблонов с dotnet new search помощью или dotnet new list.

Tip

Project и шаблоны решений отображаются в диалоговом окне Visual Studio "Создание нового project", но шаблоны элементов не отображаются в диалоговом окне "Добавление>нового элемента". Пользователи могут получить доступ к шаблонам элементов из интерфейса командной dotnet new строки.

Структура шаблона

Шаблон — это папка на диске, которая содержит две вещи: исходные файлы шаблона и специальную .template.config вложенную папку. При запуске dotnet new <shortName>пользователя подсистема шаблонов копирует исходные файлы в выходное расположение и применяет любую конфигурацию, определенную для шаблона.

mytemplate/
├── console.cs
├── readme.txt
└── .template.config/
    ├── template.json
    └── icon.png

Исходные файлы могут быть любым типом файла. Обработчик шаблонов не требует внедрения специальных маркеров или маркеров в исходный код. В нем используются файлы as-is, что означает, что вы можете создавать, запускать и отлаживать исходный проект шаблона точно так же, как обычный проект .NET. Чтобы превратить существующий проект в шаблон, добавьте .template.config/template.json файл в корневой каталог проекта.

При необходимости можно внедрить маркеры подстановки, привязанные к параметрам шаблона (символам), непосредственно в исходные файлы шаблона и имена файлов. Если маркеры не являются допустимыми исходным кодом, вы не сможете создавать, запускать или отлаживать исходный проект перед развертыванием в качестве шаблона. Маркеры не влияют на проекты, создаваемые пользователями из развернутого шаблона, так как подсистема шаблонов заменяет их во время создания проекта.

Единственным обязательным файлом template.jsonявляется внутри .template.config . Этот файл сообщает обработчику шаблонов все необходимое: имя шаблона, короткое имя, автор, классификации и любые пользователи параметров, которые могут передаваться при создании из шаблона. Вы также можете поместить icon.png файл в папку .template.config . Терминал не отображает значки, но Visual Studio отображает значок рядом с шаблоном в диалоговом окне "Создание проекта". 128×128 PNG хорошо работает.

Файл template.json

Файл template.json является единственным обязательным элементом конфигурации в шаблоне. Он находится в папке .template.config и сообщает обработчику шаблонов, как представить и обработать шаблон. В следующей таблице описаны общие обязательные и необязательные поля:

Поле	Type	Обязательно	Description
$schema	URI	No	Схема JSON для template.json. Установите для https://json.schemastore.org/template включения IntelliSense в редакторах, таких как Visual Studio Code.
author	string	No	Автор шаблона.
classifications	array(string)	No	Пользователи тегов могут использовать для поиска шаблона или dotnet new searchdotnet new list. Эти значения отображаются в столбце "Теги " списка шаблонов.
description	string	No	Описание того, что создает шаблон.
identity	string	Да	Уникальный идентификатор шаблона.
name	string	Да	Отображаемое имя шаблона для пользователей.
shortName	string	Да	Короткое имя, передаваемого пользователям для dotnet new создания из шаблона, например console или classlib.
sourceName	string	No	Строка в исходных файлах и именах файлов, которые подсистема шаблонов заменяет именем, которое пользователь предоставляет через -n или --name. Если пользователь не предоставляет имя, подсистема использует текущее имя каталога.
preferNameDirectory	boolean	No	Когда true и пользователь предоставляет имя, но нет выходного каталога, подсистема шаблонов создает новый каталог с таким именем вместо записи файлов в текущий каталог. Значение по умолчанию — false.
tags	object	No	Метаданные, определяющие свойства, такие как язык шаблона и тип. Используется tags.language для языка и tags.type для project, itemили solution.

Два поля заслуживают дополнительного внимания. Поле sourceName заключается в том, как шаблоны обрабатывают именование: задайте для него строку, которая отображается в именах файлов и исходном коде (например MyTemplate), а модуль шаблонов заменяет каждое вхождение любым именем, которое пользователь передает при создании шаблона. Возможности classifications обнаружения полей; выберите теги, которые точно описывают назначение шаблона, чтобы пользователи могли найти его при поиске.

Ниже приведено минимальное значение template.json для шаблона консоли:

{
  "$schema": "https://json.schemastore.org/template",
  "author": "Your Name",
  "classifications": [ "Common", "Console" ],
  "description": "Creates a console application.",
  "identity": "MyCompany.ConsoleTemplate.CSharp",
  "name": "My Console App",
  "shortName": "myconsole",
  "sourceName": "MyConsoleApp",
  "tags": {
    "language": "C#",
    "type": "project"
  }
}

Полная схема доступна в хранилище схем JSON. Дополнительные параметры конфигурации, такие как включение условного файла, действия после создания и шаблоны с несколькими проектами, см. вики-сайте dotnet/templating GitHub.

Параметры шаблона (символы)

В symbols разделе template.json определяются параметры, которые пользователи могут передавать при создании из шаблона. Каждый символ становится параметром dotnet new <shortName>CLI, поэтому имя ClassName символа становится --ClassName (или -C если вы определяете короткое имя).

Каждая запись символа поддерживает следующие распространенные параметры:

Setting	Description
type	Должен быть "parameter" для параметров, доступных для пользователей.
description	Отображается в выходных данных шаблона при запуске dotnet new <shortName> -?пользователей.
datatype	Ожидаемый тип данных, например "text", "bool"или "choice".
replaces	Строка в исходном содержимом файла, заменяемая подсистемой шаблонов значением параметра.
fileRename	Строка в именах исходных файлов, которые подсистема шаблонов заменяет значением параметра.
defaultValue	Значение, используемое, когда пользователь не предоставляет параметр.

Параметры replaces — fileRename это способ подстановки символов. Когда пользователь предоставляет значение, подсистема шаблонов заменяет каждое вхождение replaces строки внутри содержимого файла и каждое вхождение fileRename строки в именах файлов. Если пользователь не предоставляет значение, defaultValue он используется вместо него.

Например, следующий символ позволяет пользователям задавать имя класса при создании из шаблона. Файл переименован и класс внутри него обновляется для сопоставления:

"symbols": {
  "ClassName": {
    "type": "parameter",
    "description": "The name of the code file and class.",
    "datatype": "text",
    "replaces": "StringExtensions",
    "fileRename": "StringExtensions",
    "defaultValue": "StringExtensions"
  }
}

С помощью этого символа пользователь может запуститься dotnet new <shortName> --ClassName MyHelpers для создания файла с именем класса с именем MyHelpers.csMyHelpers. Без флага файл и класс сохраняют имя StringExtensionsпо умолчанию.

Чтобы проверить параметры, предоставляемые шаблоном, передайте -? его короткое имя после установки:

dotnet new <shortName> -?

Пакеты шаблонов

Пакет шаблона — это файл NuGet (.nupkg), который объединяет один или несколько шаблонов вместе. Когда пользователь устанавливает пакет шаблона, подсистема шаблонов .NET одновременно регистрирует каждый шаблон внутри него. Пакеты — это стандартный способ распространения шаблонов. Публикация одного пакета для NuGet.org или частного веб-канала NuGet или совместного использования локального .nupkg файла, а пользователи получают всю коллекцию с одной командой.

Чтобы создать пакет шаблона, используйте файл проекта C# (.csproj), настроенный как проект упаковки , а не проект компиляции. Основные параметры, которые делают эту работу:

Setting	Ценность	Purpose
PackageType	Template	Помечает пакет как пакет шаблона, чтобы он отображалась в dotnet new search результатах.
IncludeContentInPack	true	Включает файлы содержимого в пакет NuGet.
IncludeBuildOutput	false	Запрещает добавление скомпилированных двоичных файлов в пакет.
ContentTargetFolders	content	Помещает папки шаблона в content папку пакета NuGet, где модуль шаблонов ожидает их поиска.

Шаблон templatepack проекта предоставляет самый простой способ создания проекта упаковки:

1. Установите Microsoft. Пакет NuGet TemplateEngine.Authoring.Templates:

   dotnet new install Microsoft.TemplateEngine.Authoring.Templates
   

2. Создайте проект упаковки:

   dotnet new templatepack -n <PackageName>
   

Созданный проект включает правильные .csproj параметры, content папку для шаблонов и задачи MSBuild для проверки шаблонов и необязательной локализации.

Полное пошаговое руководство по созданию, упаковке и публикации пакета шаблона см. в руководстве по созданию пакета шаблона.

Тестирование шаблона локально

Во время разработки шаблона установите шаблон непосредственно из папки, чтобы протестировать его без создания пакета. Передайте путь к каталогу, который содержит папку .template.config :

dotnet new install ./mytemplate/

Чтобы просмотреть все установленные пакеты шаблонов и точную команду для удаления каждого из них, выполните команду dotnet new uninstall без аргументов:

dotnet new uninstall

Чтобы удалить шаблон, установленный из каталога, передайте тот же путь к каталогу, который использовался для его установки:

dotnet new uninstall ./mytemplate/

Когда вы будете готовы предоставить общий доступ к шаблону, упаковайте его как пакет NuGet (см. пакеты шаблонов) и распределите его. Пользователи устанавливают опубликованный шаблон с dotnet new install одним из следующих исходных аргументов:

• Идентификатор пакета NuGet, который устанавливает последнюю стабильную версию из источников NuGet, настроенных для текущего каталога:

  dotnet new install AdatumCorporation.ConsoleTemplate.CSharp
  

• Идентификатор пакета NuGet с настраиваемым URL-адресом веб-канала. Этот --nuget-source параметр использует указанный веб-канал в дополнение к настроенным источникам NuGet только для этой установки:

  dotnet new install AdatumCorporation.ConsoleTemplate.CSharp --nuget-source https://mynugetfeed.example.com/v3/index.json
  

• Путь к локальному .nupkg файлу:

  dotnet new install ./AdatumCorporation.ConsoleTemplate.CSharp.1.0.0.nupkg
  

Предупреждение

Шаблоны могут выполнять задачи MSBuild и произвольный код во время создания проекта. Установите только шаблоны из источников, которым вы доверяете.

Чтобы удалить пакет, установленный из источника NuGet или локального .nupkg файла, используйте идентификатор пакета NuGet:

dotnet new uninstall AdatumCorporation.ConsoleTemplate.CSharp

Встроенные шаблоны SDK не отображаются в списке удаления и не могут быть удалены с dotnet new uninstallпомощью .

Локализация шаблона

Модуль шаблонов .NET поддерживает необязательное локализацию метаданных шаблона. Если вы предоставляете файлы локализации, такие узлы, как dotnet new и диалоговое окно "Создать Visual Studio Project", отображает имя шаблона, описание и сведения о символах на языке пользователя вместо исходного созданного языка.

Следующие поля шаблона поддерживают локализацию:

• name
• author
• description
• Символы description и displayName
• Описание и отображаемое имя для каждого выбора в параметре выбора
• description Действие post иmanualInstructions

Чтобы добавить локализацию, создайте вложенную папку localize внутри .template.config и добавьте один JSON-файл на язык. Присвойте каждому файлу templatestrings.<lang-code>.json<lang-code> допустимое CultureInfo имя, например pt-BR, zh-Hansили de. Каждый файл содержит пары "ключ-значение", где ключ является путем к элементу в template.json, используя / в качестве разделителя для вложенных полей.

Например, при указании следующего template.json содержимого:

{
  "$schema": "https://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."
}

Модуль шаблонов анализирует эти файлы при загрузке сведений о шаблоне и возвращает локализованные значения автоматически на основе текущего языка и региональных параметров пользовательского интерфейса. Дополнительные действия от пользователя не требуются.

Локализация является необязательной. Если вы не включаете файлы локализации, шаблон работает нормально и всегда отображает значения из template.json. Дополнительные сведения см. на странице локализации dotnet/templating wiki.

Интеграция Visual Studio

диалоговое окно "Создание нового проекта" Visual Studio использует подсистему шаблонов .NET для шаблонов .NET проектов. Шаблоны, которые вы создаете для dotnet new работы в Visual Studio тоже без дополнительной настройки. Когда пользователь устанавливает пакет шаблона с dotnet new installпомощью Visual Studio автоматически обнаруживает и отображает эти шаблоны в диалоговом окне.

Project и шаблоны решений отображаются в диалоговом окне "Создание нового project" вместе со встроенными шаблонами SDK. Пользователи могут найти шаблоны по имени, языку или тегам из classifications поля в файле шаблона template.json . Точные классификации помогают поверхности шаблона в правильных категориях фильтров, поэтому тщательно выбирайте их. Чтобы предоставить шаблону полированный внешний вид в диалоговом окне, добавьте icon.png.template.config в папку — Visual Studio отображает его рядом с именем шаблона.

Шаблоны элементов в настоящее время не отображаются в диалоговом окне "Добавление>нового элемента ". Пользователи по-прежнему могут использовать шаблоны элементов с командой dotnet new в терминале.

Чтобы сделать шаблон доступен для Visual Studio пользователей, которые еще не установили его, опубликуйте пакет шаблона в nuget.org. Диалоговое окно "Создание проекта" содержит дополнительные шаблоны из параметра поиска в Интернете, который выполняет поиск nuget.org для пакетов шаблонов. Когда пользователь устанавливает пакет с помощью этого параметра, Visual Studio использует тот же механизм установки, что dotnet new installи .

Более подробное руководство по интеграции с Visual Studio, например управление порядком сортировки шаблонов и настройкой дополнительных параметров интегрированной среды разработки, см. в репозитории шаблонов с примером с помощью Sayed Hashimi.

Связанные материалы

• Учебное пособие: Создание шаблона элемента
• Руководство. Создание шаблона проекта
• Руководство. Создание пакета шаблона
• команда dotnet new
• dotnet/templating GitHub вики-сайт репозитория
• примеры шаблонов