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

  • Статья

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

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

Совет

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

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

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

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

  • Пакет SDK для .NET 7.0.100 или более поздняя версия.

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

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

Важно!

Эта статья написана для .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 Используйте команду, чтобы просмотреть список всех параметров и вложенных команд.

Создание нужных папок

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

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

Структура папок должна выглядеть так, как показано ниже.

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

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

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

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

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". Вы можете создать шаблон любого типа. Значения item и project — это общие рекомендуемые имена .NET, которые позволяют без усилий фильтровать типы шаблонов при поиске.

Элемент classifications представляет столбец tags, который отображается после запуска команды 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: file StringExtensions.cs и class 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, вы можете установить шаблон. В окне терминала перейдите к папке extensions и выполните приведенную ниже команду, чтобы установить шаблон, расположенный в текущей папке:

  • В 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, чтобы получить список установленных пакетов шаблонов и команду удаления для каждого из них.

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

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

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