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

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

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

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

Подсказка

Шаблоны элементов не отображаются в диалоговом окне добавления>нового элемента Visual Studio.

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

  • Создайте класс для шаблона элемента.
  • Создайте папку и файл конфигурации шаблона.
  • Установите шаблон с указанного пути к файлу.
  • Проверьте шаблон элемента.
  • Удалите шаблон элемента.

Предпосылки

  • .NET 9 или более поздней версии.

  • В справочной статье описываются основы шаблонов и их объединения. Некоторые из этих сведений вновь приведены здесь.

  • Откройте терминал и перейдите в папку, в которой будут храниться и тестировать шаблоны.

Создание необходимых папок

В этой серии используется рабочая папка, в которой содержится источник шаблона, а для тестирования шаблонов используется папка тестирования. Рабочая папка и папка тестирования должны находиться в той же родительской папке.

Сначала создайте родительскую папку, имя не имеет значения. Затем создайте две вложенные папки с именем working и test. В рабочей папке создайте вложенную папку с именем содержимого.

Структура папок должна выглядеть следующим образом.

parent_folder
├───test
└───working
    └───content

Создание шаблона элемента

Шаблон элемента — это определенный тип шаблона, который содержит один или несколько файлов. Эти типы шаблонов полезны, если у вас уже есть проект, и вы хотите создать другой файл, например файл конфигурации или файл кода. В этом примере создается класс, который добавляет метод расширения в тип строки.

В терминале перейдите в папку working\content и создайте новую подпапку под именем extensions.

working
└───content
    └───extensions

Перейдите в папку расширений и создайте файл с именем StringExtensions.cs. Откройте файл в текстовом редакторе. Этот класс предоставляет метод расширения с именем Reverse , который изменяет содержимое строки. Вставьте следующий код и сохраните файл:

namespace System;

public static class StringExtensions
{
    public static string Reverse(this string value)
    {
        char[] tempArray = value.ToCharArray();
        Array.Reverse(tempArray);
        return new string(tempArray);
    }
}

Теперь, когда содержимое шаблона завершено, создайте конфигурацию шаблона.

Создание конфигурации шаблона

В этой части руководства папка шаблона находится в рабочей\content\extensions.

Шаблоны распознаются .NET, так как они имеют специальную папку и файл конфигурации, существующий в корне папки шаблона.

Сначала создайте новую вложенную папку с именем .template.config, и перейдите в неё. Затем создайте новый файл с именем template.json. Структура папок должна выглядеть следующим образом:

working
└───content
    └───extensions
        └───.template.config
                template.json

Откройте template.json с любимым текстовым редактором и вставьте следующий код JSON и сохраните его.

{
    "$schema": "http://json.schemastore.org/template",
    "author": "Me",
    "classifications": [ "Common", "Code" ],
    "identity": "ExampleTemplate.StringExtensions",
    "name": "Example templates: string extensions",
    "shortName": "stringext",
    "tags": {
      "language": "C#",
      "type": "item"
    },
    "symbols": {
      "ClassName":{
        "type": "parameter",
        "description": "The name of the code file and class.",
        "datatype": "text",
        "replaces": "StringExtensions",
        "fileRename": "StringExtensions",
        "defaultValue": "StringExtensions"
      }
    }
  }

Этот файл конфигурации содержит все параметры шаблона. Вы можете просмотреть основные параметры, такие как name и shortName, но также есть параметр tags/type, который задан item. Это классифицирует ваш шаблон как шаблон "элемент". Нет ограничений на тип создаваемого шаблона. Значения item и project являются распространенными именами, которые рекомендует .NET, чтобы пользователи могли легко отбирать нужный тип шаблона.

Элемент classifications представляет столбец тегов, который отображается при запуске dotnet new и получении списка шаблонов. Пользователи также могут выполнять поиск на основе тегов классификации. Не путайте tags свойство в файле template.json со списком classifications тегов. Они два разных понятия, которые, к сожалению, называются одинаковыми. Полная схема файла template.json найдена в хранилище схем JSON и описана в справочнике по template.json. Дополнительные сведения о файлеtemplate.json см. вики-сайте dotnet.

Часть symbols этого объекта JSON используется для определения параметров, которые можно использовать в шаблоне. В этом случае определен ClassNameодин параметр. Определенный параметр содержит следующие параметры:

  • type — Это обязательный параметр и должен иметь значение parameter.
  • description — Описание параметра, который выводится в справке шаблона.
  • datatype — Тип данных значения параметра при использовании параметра.
  • replaces — задает текстовое значение, которое должно быть заменено во всех файлах шаблонов значением параметра.
  • fileRename — Аналогично replaces, это указывает текстовое значение, которое заменяется в именах всех файлов шаблонов значением параметра.
  • defaultValue — значение по умолчанию этого параметра, если параметр не указан пользователем.

При использовании шаблона пользователь может указать значение параметра ClassName , и это значение заменяет все вхождения StringExtensions. Если значение не указано, defaultValue используется. Для этого шаблона существует два вхождения StringExtensions: файл StringExtensions.cs и класс StringExtensions. defaultValue Так как параметр имеет StringExtensionsзначение, имя файла и имя класса остаются неизменными, если параметр не указан при использовании шаблона. Если указано значение, например dotnet new stringext -ClassName MyExts, файл переименован MyExts.cs , а класс переименован в MyExts.

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

dotnet new stringext -?

Это создает следующие выходные данные:

Example templates: string extensions (C#)
Author: Me

Usage:
  dotnet new stringext [options] [template options]

Options:
  -n, --name <name>       The name for the output being created. If no name is specified, the name of the output directory is used.
  -o, --output <output>   Location to place the generated output.
  --dry-run               Displays a summary of what would happen if the given command line were run if it would result in a template creation.
  --force                 Forces content to be generated even if it would change existing files.
  --no-update-check       Disables checking for the template package updates when instantiating a template.
  --project <project>     The project that should be used for context evaluation.
  -lang, --language <C#>  Specifies the template language to instantiate.
  --type <item>           Specifies the template type to instantiate.

Template options:
  -C, --ClassName <ClassName>  The name of the code file and class.
                               Type: text
                               Default: StringExtensions

Теперь, когда у вас есть действительный файл.template.config/template.json , шаблон готов к установке. В терминале перейдите в папку расширений и выполните следующую команду, чтобы установить шаблон, расположенный в текущей папке:

  • В Windows: dotnet new install .\
  • В Linux или macOS: dotnet new install ./

Эта команда выводит список установленных шаблонов, которые должны содержать ваши.

The following template packages will be installed:
   <root path>\working\content\extensions

Success: <root path>\working\content\extensions installed the following templates:
Templates                                         Short Name               Language          Tags
--------------------------------------------      -------------------      ------------      ----------------------
Example templates: string extensions              stringext                [C#]              Common/Code

Тестирование шаблона элемента

Теперь, когда у вас установлен шаблон элемента, проверьте его.

  1. Перейдите в тестовую папку.

  2. Создайте новое консольное приложение с помощью dotnet new console, которое формирует рабочий проект, легко тестируемый командой dotnet run.

    dotnet new console

    Вы получите выходные данные, аналогичные приведенным ниже.

    The template "Console Application" was created successfully.

Processing post-creation actions...
Running 'dotnet restore' on C:\test\test.csproj...
  Restore completed in 54.82 ms for C:\test\test.csproj.

Restore succeeded.

  3. Запустите проект с помощью следующей команды.

    dotnet run

    Вы получите следующие выходные данные.

    Hello, World!

  4. Запустите dotnet new stringext , чтобы создать файл StringExtensions.cs из шаблона.

    dotnet new stringext

    Вы получите следующие выходные данные.

    The template "Example templates: string extensions" was created successfully.

  5. Измените код в Program.cs , чтобы перевернуть "Hello, World!" строку с помощью метода расширения, предоставленного шаблоном.

    Console.WriteLine("Hello, World!".Reverse());

    Запустите программу снова и увидьте, что результат обратный.

    dotnet run

    Вы получите следующие выходные данные.

    !dlroW ,olleH

Поздравляю! Вы создали и развернули шаблон элемента с помощью .NET. При подготовке к следующей части этой серии учебников удалите созданный шаблон. Не забудьте удалить все файлы и папки в тестовой папке. Это возвращает систему в чистое состояние, готовое к следующей части этой серии руководств.

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

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

  • В Windows: dotnet new uninstall .\
  • В Linux или macOS: dotnet new uninstall ./

Эта команда выводит список шаблонов, которые были удалены, которые должны включать ваши.

Success: <root path>\working\content\extensions was uninstalled.

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

Дальнейшие шаги

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

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

  • Last updated on