Руководство. Создание пакета шаблона

Статья
12/18/2024

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

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

В этой части серии вы узнаете, как:

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

Необходимые условия

Завершите часть 1 и часть 2 этого учебного руководства.

В этом руководстве используются два шаблона, созданные в первых двух частях этой серии учебников. Можно использовать другой шаблон только в том случае, если вы скопируете шаблон в виде папки в папку working\content.
Откройте командную строку и перейдите в рабочую папку .
Установите .NET 8 или .NET 9.
Установите шаблон Microsoft.TemplateEngine.Authoring.Templates из канала пакетов NuGet.
- Выполните команду dotnet new install Microsoft.TemplateEngine.Authoring.Templates из терминала.

Создайте пакетный проект шаблона

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

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

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

Созданный пакет будет включать ранее созданные шаблоны элемента и проекта.

Пакет 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 ...

Описание 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.

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

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

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

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

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

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, о большинстве из которых вы уже узнали, см. в статье .

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