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

Пакет SDK для .NET поставляется со многими шаблонами, уже установленными и готовыми для использования. Командаdotnet new — это не только способ использования шаблона, но и установка и удаление шаблонов. Вы можете создать собственные пользовательские шаблоны для любого типа проекта, например приложения, службы, инструмента или библиотеки классов. Можно даже создать шаблон, который выводит один или несколько независимых файлов, например файл конфигурации.

Пользовательские шаблоны можно установить из пакета NuGet на любом веб-канале NuGet, ссылаясь непосредственно на файл NuGet .nupkg или указав каталог файловой системы, содержащий шаблон. Модуль шаблонов предлагает функции, позволяющие заменить значения, включать и исключать файлы, а также выполнять пользовательские операции обработки при использовании шаблона.

Модуль шаблонов является открытым исходным кодом, и репозиторий кода в Сети находится в dotnet/templating на GitHub. Дополнительные шаблоны, включая шаблоны сторонних производителей, можно найти с помощью dotnet new search. Дополнительные сведения о создании и использовании пользовательских шаблонов см. в разделе "Создание собственных шаблонов для dotnet new" и вики-сайта репозитория dotnet/templating на GitHub.

Чтобы выполнить пошаговое руководство и создать шаблон, ознакомьтесь с руководством по созданию пользовательского шаблона для dotnet.

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

При установке пакета SDK для .NET вы получаете более десяти встроенных шаблонов для создания проектов и файлов, включая консольные приложения, библиотеки классов, проекты модульных тестов, приложения 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 в корневом каталоге шаблона. Файл предоставляет сведения о конфигурации для шаблонного движка. Минимальная конфигурация требует элементов, отображаемых в следующей таблице, достаточно для создания функционального шаблона.

Полная схема файла template.json находится в хранилище схем JSON. Дополнительные сведения о файлеtemplate.json см. вики-сайте dotnet. Более подробные примеры и сведения о том, как сделать шаблоны видимыми в Visual Studio, см. в ресурсах, созданных Сайедом Хашими.

Пример

Например, вот папка шаблона, содержащая два файла содержимого: 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 можно локализуть. Если шаблон локализован для языка, соответствующего текущему языковому стандарту, его элементы отображаются на том же языке, что и интерфейс командной строки. Локализация является необязательной при создании новых шаблонов.

Локализуемые элементы шаблона:

• Имя
• Автор
• Описание
• Символы
  • Описание
  • Отображаемое имя
  • Описания и отображаемое имя вариантов выбора параметров
• Действия после публикации
  • Описание
  • Инструкции из руководства

Файлы локализации имеют формат JSON, и для каждой культуры должен существовать только один файл. Соглашение об именовании: templatestrings.<lang code>.jsonгде lang code соответствует одному из параметров CultureInfo . Все файлы локализации должны находиться в папке .template-config\localize .

Код JSON локализации состоит из пар ключ-значение.

• Основное — это ссылка на элемент template.json, который должен быть локализован. Если элемент является дочерним, используйте полный путь с / разделителем.
• Значением является строка локализации элемента, заданного ключом.

Дополнительные сведения о локализации шаблонов см. на странице локализации вики dotnet templating.

Пример

Например, вот 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 требует .NET Framework в Windows и Mono в Linux и macOS.

.csproj файл немного отличается от традиционного файла .csproj кодового проекта. Обратите внимание на следующие параметры:

1. Параметр <PackageType> добавляется и устанавливается на Template.
2. Параметр <PackageVersion> добавляется и устанавливается в допустимый номер версии NuGet.
3. Параметр <PackageId> добавляется и устанавливается на уникальный идентификатор. Этот идентификатор используется для удаления пакета шаблонов и используется веб-каналами NuGet для регистрации пакета шаблонов.
4. Параметры универсальных метаданных должны быть заданы: <Title>, <Authors>, <Description>и <PackageTags>.
5. Этот <TargetFramework> параметр должен быть задан, даже если двоичный файл, созданный процессом шаблона, не используется. В приведенном ниже примере задано значение netstandard2.0.

Пакет шаблона в виде пакета NuGet nupkg требует, чтобы все шаблоны хранились в папке содержимого в пакете. Для установки созданного файла .nupkg в виде пакета шаблонов необходимо добавить несколько дополнительных параметров в файл .csproj.

1. Для параметра <IncludeContentInPack> установлено true, чтобы включить любой файл, который проект определяет как содержимое в пакете NuGet.
2. Параметр <IncludeBuildOutput> установлен на false, чтобы исключить все двоичные файлы, генерируемые компилятором, из пакета NuGet.
3. Для <ContentTargetFolders> параметра задано contentзначение . Это гарантирует, что файлы, заданные как содержимое , хранятся в папке содержимого в пакете NuGet. Эта папка в пакете 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 install для установки пакета шаблона.

Установка шаблонного пакета из NuGet-пакета, доступного на nuget.org

Используйте идентификатор пакета 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

Укажите путь к файлу пакета NuGet nupkg .

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, отображаются в списке. Пакеты шаблонов, встроенные в пакет SDK для .NET, не отображаются.

Удалите пакет шаблона

Используйте команду 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>

См. также

• Создание пользовательского шаблона для dotnet new (учебник)
• dotnet/templating репозиторий GitHub для Wiki
• примеры шаблонов
• Создание собственных шаблонов для dotnet new
• схема template.json в хранилище схем JSON