Учебник. Создание пакета шаблонов

Статья
10/07/2023

С помощью .NET можно создавать и развертывать шаблоны, которые создают проекты, файлы и даже ресурсы. Это третья часть серии руководств по созданию, установке и удалению шаблонов с помощью команды dotnet new.

Полный шаблон можно просмотреть в репозитории GitHub примеров .NET.

Из этой части вы узнаете, как выполнять такие задачи:

Создайте пакет шаблона с помощью пакета NuGet Microsoft.TemplateEngine.Authoring.Templates .
Установите пакет шаблона из файла пакета NuGet.
Удалите пакет шаблона по идентификатору пакета.

Создайте проект *.csproj для создания пакета шаблона.
Настройте файл проекта для упаковки.
Установите пакет шаблона из файла пакета NuGet.
Удалите пакет шаблона по идентификатору пакета.

Необходимые компоненты

Изучите первую и вторую части этой серии руководств.

В этом руководстве используются два шаблона, созданные в первых двух частях этой серии учебников. Вы можете использовать другой шаблон, если вы копируете шаблон в папку working\content .
Откройте терминал и перейдите в папку working\templates.

Установите .NET 8.
Microsoft.TemplateEngine.Authoring.Templates Установите шаблон из веб-канала пакетов NuGet.
- dotnet new install Microsoft.TemplateEngine.Authoring.Templates Выполните команду из терминала.

Важно!

Эта статья написана для .NET 7. Однако он также относится к .NET 6 и предыдущим версиям с одним отличием: dotnet new синтаксис отличается. Подкомандам list, installsearchи uninstall подкомандам должны быть --list, --install--searchи --uninstall параметры соответственно.

Например, dotnet new install команда в .NET 7 становится dotnet new --install в .NET 6. dotnet new --help Используйте команду, чтобы просмотреть список всех параметров и вложенных команд.

Создание проекта для пакета шаблонов

Пакет шаблона — это один или несколько шаблонов, упакованных в пакет NuGet. При установке или удалении такого пакета добавляются или удаляются сразу все содержащиеся в нем шаблоны.

Пакет шаблонов имеет формат файла пакета NuGet (NUPKG). Как и любой другой пакет NuGet, пакет шаблонов можно передать в веб-канал NuGet. Эта dotnet new install команда поддерживает установку пакетов шаблонов из веб-канала пакетов NuGet, NUPKG-файла или каталога с шаблоном.

Для компиляции кода и создания двоичного файла обычно используется файл проекта C#. Но проект можно использовать и для создания пакета шаблонов. Изменив параметры файла CSPROJ, можно не выполнять компиляцию кода, а добавить все ресурсы в шаблон. Во время сборки этого проекта создается пакет NuGet с пакетом шаблонов.

Созданный пакет будет содержать ранее созданные [элемент] и (cli-templates-create-item-template.md) и шаблоны проектов .

Пакет Microsoft.TemplateEngine.Authoring.Templates содержит шаблоны, полезные для разработки шаблонов . Чтобы установить этот пакет, nuget.org должен быть доступен в качестве веб-канала NuGet в рабочем каталоге.

В рабочей папке выполните следующую команду, чтобы создать пакет шаблона:

dotnet new templatepack -n "AdatumCorporation.Utility.Templates"

Параметр -n задает имя файла проекта AdatumCorporation.Utility.Templates.csproj. Отобразится результат примерно такого содержания:

The template "Template Package" was created successfully.

Processing post-creation actions...
Description: Manual actions required
Manual instructions: Open *.csproj in the editor and complete the package metadata configuration. Copy the templates to _content_ folder. Fill in README.md.

Затем откройте файл AdatumCorporation.Utility.Templates.csproj в редакторе кода и заполните его в соответствии с указаниями в шаблоне:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <!-- The package metadata. Fill in the properties marked as TODO below -->
    <!-- Follow the instructions on https://learn.microsoft.com/nuget/create-packages/package-authoring-best-practices -->
    <PackageId>AdatumCorporation.Utility.Templates</PackageId>
    <PackageVersion>1.0</PackageVersion>
    <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>
    <PackageProjectUrl>https://your-url</PackageProjectUrl>

    <PackageType>Template</PackageType>
    <TargetFramework>net8.0</TargetFramework>
    <IncludeContentInPack>true</IncludeContentInPack>
    <IncludeBuildOutput>false</IncludeBuildOutput>
    <ContentTargetFolders>content</ContentTargetFolders>
    <NoWarn>$(NoWarn);NU5128</NoWarn>
    <NoDefaultExcludes>true</NoDefaultExcludes>
    ... cut for brevity ...

В рабочей папке выполните следующую команду, чтобы создать пакет шаблона:

dotnet new console -n AdatumCorporation.Utility.Templates

The template "Console Application" was created successfully.

Processing post-creation actions...
Running 'dotnet restore' on .\AdatumCorporation.Utility.Templates.csproj...
  Restore completed in 52.38 ms for C:\code\working\AdatumCorporation.Utility.Templates.csproj.

Restore succeeded.

Удалите файл Program.cs. Новый шаблон проекта создает этот файл, но он не используется подсистемой шаблонов.

Затем откройте файл AdatumCorporation.Utility.Templates.csproj в избранном редакторе и замените содержимое следующим XML:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <PackageId>AdatumCorporation.Utility.Templates</PackageId>
    <PackageVersion>1.0</PackageVersion>
    <Title>AdatumCorporation Templates</Title>
    <Authors>Me</Authors>
    <Description>Templates to use when creating an application for Adatum Corporation.</Description>
    <PackageTags>dotnet-new;templates;adatum</PackageTags>
    <PackageProjectUrl>https://your-url</PackageProjectUrl>

    <PackageType>Template</PackageType>
    <TargetFramework>netstandard2.0</TargetFramework>
    <IncludeContentInPack>true</IncludeContentInPack>
    <IncludeBuildOutput>false</IncludeBuildOutput>
    <ContentTargetFolders>content</ContentTargetFolders>
    <NoWarn>$(NoWarn);NU5128</NoWarn>
    <NoDefaultExcludes>true</NoDefaultExcludes>
  </PropertyGroup>

  <ItemGroup>
    <Content Include="content\**\*" Exclude="content\**\bin\**;content\**\obj\**" />
    <Compile Remove="**\*" />
  </ItemGroup>

</Project>

Описание XML проекта

Параметры <PropertyGroup> в фрагменте XML разбиваются на две группы.

Первая группа отвечает за свойства, необходимые для пакета NuGet. Четыре <Package*> параметра должны иметь значение свойств пакета NuGet для идентификации пакета в веб-канале NuGet. Значение <PackageId> , используемое NuGet, также используется для удаления пакета шаблона. Остальные параметры, такие как <Title> и <PackageTags>, должны быть связаны с метаданными, отображаемыми на веб-канале NuGet и диспетчере пакетов .NET. См. подробнее о параметрах NuGet в описании свойств NuGet и MSBuild.

Примечание.

Чтобы убедиться, что пакет шаблона отображается в dotnet new search результатах,<PackageType> необходимо задать значение Template.

Во второй группе <TargetFramework> параметр гарантирует правильность работы MSBuild при выполнении команды пакета для компиляции и упаковки проекта. Группа также включает параметры, связанные с настройкой проекта для включения шаблонов в соответствующую папку в пакет NuGet при его создании:

Параметр <NoWarn> подавляет предупреждающее сообщение, которое не применяется к проектам пакетов шаблонов.
Этот <NoDefaultExcludes> параметр гарантирует, что файлы и папки, начинающиеся с . (например .gitignore), являются частью шаблона. Поведение пакетов NuGet по умолчанию — игнорировать эти файлы и папки.

<ItemGroup> содержит два элемента. Во-первых, <Content> элемент содержит все в папке шаблонов как содержимое. Он также предотвращает добавление папки bin или obj и компиляцию кода (если вы выполняли тестирование и компиляцию шаблонов). Во-вторых, <Compile> элемент исключает все файлы кода из компиляции независимо от того, где они находятся. Этот параметр запрещает проекту, который используется для создания пакета шаблона, пытаться скомпилировать код в иерархии папок шаблонов .

Совет

Дополнительные сведения о параметрах метаданных NuGet см. в разделе "Упаковка шаблона" в пакет NuGet (nupkg-файл).

Созданный файл проекта включает задачи разработки шаблонов MSBuild и параметры локализации.

  <PropertyGroup>
    <LocalizeTemplates>false</LocalizeTemplates>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.TemplateEngine.Tasks" Version="*" PrivateAssets="all" IsImplicitlyDefined="true"/>
  </ItemGroup>

Важно!

Папка содержимого содержит папку SampleTemplate . Удалите эту папку, так как она была добавлена в шаблон разработки для демонстрационных целей.

Эти задачи MSBuild обеспечивают проверку шаблонов и локализацию возможностей шаблонов . Локализация отключена по умолчанию. Чтобы включить создание файлов локализации, задайте для этого LocalizeTemplates значения true.

Упаковка и установка

Сохраните файл проекта. Перед созданием пакета шаблонов убедитесь, что создана правильная структура папок. Любой шаблон, который необходимо упаковать, должен быть помещен в отдельную папку в папке templates. Структура папок должна выглядеть примерно так:

working
│   AdatumCorporation.Utility.Templates.csproj
└───content
    ├───extensions
    │   └───.template.config
    │           template.json
    └───consoleasync
        └───.template.config
                template.json

Папка содержимого содержит две папки: расширения и consoleasync.

В окне терминала, находясь в рабочей папке, выполните команду dotnet pack. Эта команда создает проект и создает пакет NuGet в папке working\bin\Debug , как указано в следующих выходных данных:

MSBuild version 17.8.0-preview-23367-03+0ff2a83e9 for .NET
  Determining projects to restore...
  Restored C:\code\working\AdatumCorporation.Utility.Templates.csproj (in 1.16 sec).

  AdatumCorporation.Utility.Templates -> C:\code\working\bin\Release\net8.0\AdatumCorporation.Utility.Templates.dll
  Successfully created package 'C:\code\working\bin\Release\AdatumCorporation.Utility.Templates.1.0.0.nupkg'.

Затем установите пакет шаблонов с помощью команды dotnet new install. В Windows:

dotnet new install .\bin\Release\AdatumCorporation.Utility.Templates.1.0.0.nupkg

В Linux или macOS.

dotnet new install bin/Release/AdatumCorporation.Utility.Templates.1.0.0.nupkg

Вы должны увидеть результат, аналогичный приведенному ниже:

The following template packages will be installed:
   C:\code\working\AdatumCorporation.Utility.Templates\bin\Release\AdatumCorporation.Utility.Templates.1.0.0.nupkg

Success: AdatumCorporation.Utility.Templates::1.0.0 installed the following templates:
Templates                                         Short Name               Language          Tags
--------------------------------------------      -------------------      ------------      ----------------------
Example templates: string extensions              stringext                [C#]              Common/Code
Example templates: async project                  consoleasync             [C#]              Common/Console/C#9

Если пакет NuGet был передан в веб-канал NuGet, можно использовать команду dotnet new install <PACKAGE_ID>, в которой <PACKAGE_ID> совпадает с параметром <PackageId> из файла CSPROJ.

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

Независимо от того, как был установлен пакет шаблонов (непосредственно из файла NUPKG или из веб-канала NuGet), процедура удаления пакета шаблонов будет одинаковой. Определите <PackageId> шаблона, который требуется удалить. Вы можете отобразить список всех установленных шаблонов, выполнив команду dotnet new uninstall.

C:\working> dotnet new uninstall
Currently installed items:
... cut to save space ...

  AdatumCorporation.Utility.Templates
    Details:
      NuGetPackageId: AdatumCorporation.Utility.Templates
      Version: 1.0.0
      Author: Me
    Templates:
      Example templates: async project (consoleasync) C#
      Example templates: string extensions (stringext) C#
    Uninstall Command:
      dotnet new uninstall AdatumCorporation.Utility.Templates

Выполните команду dotnet new uninstall AdatumCorporation.Utility.Templates, чтобы удалить пакет шаблонов. Команда выводит сведения о том, какие пакеты шаблонов были удалены.

Поздравляем! Вы установили и удалили пакет шаблона.

Следующие шаги

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

Поделиться через