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

Статья
04/11/2023

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

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

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

Примечание.

Примеры шаблонов доступны в репозитории dotnet/templating GitHub.

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

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

Элемент	Тип	Описание
`$schema`	URI-адрес	Схема JSON для файла template.json. Редакторы, поддерживающие схемы JSON, обеспечивают возможности редактирования JSON при указании схемы. Например, в Visual Studio Code требуется, чтобы этот элемент включал поддержку IntelliSense. Используйте значение `http://json.schemastore.org/template`.
`author`	строка	Автор шаблона.
`classifications`	array(string)	Ноль или более характеристик шаблона, по которым пользователь может найти его. Если шаблон присутствует в списке шаблонов, созданных с помощью команды `dotnet new list`, классификации также приводятся в столбце Теги.
`identity`	строка	Уникальное имя шаблона.
`name`	строка	Имя шаблона, которое видят пользователи.
`shortName`	строка	Сокращенное имя по умолчанию для выбора шаблона, которое используется во всех средах, где имя шаблона указывается пользователем, а не выбирается в графическом пользовательском интерфейсе. Например, короткое имя полезно при использовании шаблонов из командной строки с помощью команд CLI.
`sourceName`	строка	Имя в исходном дереве, заменяемое именем, которое указывает пользователь. Обработчик шаблонов будет искать любое вхождение `sourceName`, упомянутого в файле конфигурации, и заменять его именами и содержимым файлов. Значение, которое нужно изменить, может быть задано с помощью параметров `-n` или `--name` при выполнении шаблона. Если имя не указано, используется текущий каталог.
`preferNameDirectory`	Логический	Указывает, следует ли создать каталог для шаблона, если указано имя, но выходной каталог не задан (вместо создания содержимого непосредственно в текущем каталоге). По умолчанию используется значение false.

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

Пример

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

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

Имя.
Автор
Description
Символы .
- Description
- Отображаемое имя.
- Описания и отображаемое имя вариантов выбора параметров
Действия после публикации
- Description
- Инструкции вручную

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

Код JSON локализации состоит из пар "ключевое значение":

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

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

Пример

Например, вот 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 в проектах кода. Обратите внимание на следующие параметры.

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

Чтобы использовать пакет шаблонов в формате пакета NuGet .nupkg, все шаблоны должны быть сохранены в папке content внутри пакета. Есть еще несколько параметров, которые нужно добавить в файл .csproj, чтобы созданный файл .nupkg можно было установить как пакет шаблонов:

Параметр <IncludeContentInPack> получает значение true, чтобы включить все файлы проекта, отмеченные в пакете NuGet как содержимое (content).
Параметр <IncludeBuildOutput> получает значение false, чтобы исключить все бинарные файлы, созданные компилятором из пакета NuGet.
Параметр <ContentTargetFolders> получает значение content. Это гарантирует, что указанные в качестве содержимого (content) файлы будут сохранены в папку content в пакете NuGet. Эта папка в пакете NuGet анализируется системой шаблонов dotnet.

Вы можете легко исключить все файлы кода из компиляции с проектом шаблона, указав элемент <Compile Remove="**\*" /> в файле проекта, внутри элемента <ItemGroup>.

Чтобы структурировать пакет шаблонов, можно поместить все шаблоны в отдельные папки, а сами эти папки шаблонов — в папку templates в том же каталоге, где расположен файл .csproj. Это позволит вам использовать один элемент проекта для включения всех файлов и папок из папки templates в качестве содержимого (content). Внутри элемента <ItemGroup> создайте элемент <Content Include="templates\**\*" Exclude="templates\**\bin\**;templates\**\obj\**" />.

Ниже приведен пример CSPROJ-файла , который следует всем этим рекомендациям. Он упаковывает дочернюю папку templates в папку пакета content и исключает из компиляции все файлы кода.

<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 и папка templates размещаются в корневом каталоге с именем project_folder. Папка templates содержит два шаблона с именами 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 search, для типа пакета NuGet задайте значение Template.

Установка пакета шаблона

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

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

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

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

Настройка

Исходные файлы и папки

template.json.

Пример

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

Пример

Упаковка шаблона в пакет NuGet (nupkg-файл)

Установка пакета шаблона

Установка пакета шаблонов из пакета NuGet, хранящегося на сайте nuget.org

Установка пакета шаблона из пользовательского источника NuGet

Установка пакета шаблонов из локального файла NUPKG

Установка пакета шаблонов из каталога в файловой системе

Получение списка установленных пакетов шаблонов

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

Создание проекта с помощью пользовательского шаблона

См. также

Обратная связь

Дополнительные ресурсы