Перейти к содержанию

Гайд по созданию шаблонов

1. Предисловие

В этом гайде рассматриваются стандартные способы создания всех 3 видов шаблонов, поддерживаемые в Visual Studio (и, может быть в VS Code), а именно:
1. Шаблоны проектов;

2. Шаблоны элементов; 3. Фрагменты кода (code snippet) в чистой Visual Studio;
4. Фрагменты кода (code snippet) с ReSharper.

2. Шаблоны проектов

2.1 Создаем основу, это можно сделать и на пустом проекте

2.1.1. Открываем мастер шаблонов

image

2.1.2. Выбираем нужный тип шаблона

image

2.1.3. По желанию сразу заполняем название/описание/добавляем иконку (можно не делать сразу, а вписать потом). Так же желательно сразу не импортировать шаблон, т.к. он импортируется без дополнительного форматирования, которое будет нужно почти в любом случае. Но если не надо, то дальнейшие шаги можно пропустить.

image

2.2. Редактируем шаблон

2.2.1. Открываем папку куда импортировали шаблон и распаковываем архив. Получаем примерно следующее:

image

Что это такое:
1._TemplateIcon.ico – стандартная иконка, которая вставляется в шаблон, если не выбрана кастомная.
2.MyTemplate.vstemplate – файл с метаданными по шаблону (название, описание и пр.).
3.Всё остальное – непосредственно файлы шаблона.

2.2.2. Редактируем шаблон (*.csproj открывает сразу всю папку и даже синтаксические ошибки будут подсвечиваться).

На этом этапе крайне желательно докрутить вообще всё (лучше не оставлять даже мелкие недочеты, т.к. потом их исправлять будет уже лень).
Так же надо расставить форматирование шаблонов. В общем случае это выглядит так:
$TemplateSchemaVariableName$
Список элементов можно посмотреть тут:
https://learn.microsoft.com/en-us/visualstudio/ide/template-parameters?view=vs-2022
А наглядно посмотреть что они делают тут:
https://www.reddit.com/r/learnprogramming/comments/w24f5q/visual_studio_2019_templates_safeprojectname/
Важно: не все элементы форматирования ведут себя одинаково в шаблонах проектов и шаблонах элементов.

image

Более продвинутые способы форматирования описаны в «дополнительно».

2.2.3. Редактируем метаданные шаблона

image

Что делают основные теги (их сильно больше, может в «дополнительно» будет их описание):
* Name – название шаблона, отображаемое в меню выбора шаблонов;
* Description – описание шаблона, отображаемое в меню выбора шаблонов;
* ProjectType– основной тип проекта по языку. Можно написать что угодно, но при изменении крайне желательно нагуглить стандартные названия. Используется при фильтрации в меню выбора шаблонов;
* ProjectSubType – подтип проекта по технологии/назначению. Можно писать что угодно, для попадания в одну из уже существующих категорий в меню выбора шаблонов, достаточно просто указать её название (чувствительно к регистру);
* SortOrder – чем выше – тем выше по списку будет шаблон. В документации написано, что для пользовательских шаблонов ничего не делает;
* CreateNewFolder – нужно ли создавать новую папку под шаблон. Может меняться пользователем при создании проекта из шаблона;
* DefaultName – название по умолчанию для проекта, создаваемого по шаблону. Может меняться пользователем при создании проекта из шаблона;
* ProvideDefaultName – использовать ли название из DefaultName при создании;
* LocationField – отображать ли поле с путем сохранения при создании проекта из шаблона;
* EnableLocationBrowserButton – отображать ли кнопку для вызова проводника для выбора пути сохранения при создании проекта из шаблона;
* CreateInPlace – определяет где создаются файлы для проекта. True – создаются прямо по указанному пути. False – создаются в месте к которому есть доступ у VisualStudio и потом копируются по указанному пути. Нужно для запар с доступом;
* Icon – имя иконки, отображаемой в меню выбора шаблонов. Должно соответствовать имени иконки из архива;
* TemplateContent – здесь располагаются ссылки на все элементы шаблона. Мультипроектные шаблоны будут описаны в «дополнительно»;
* Project – тег с описанием проекта, “File” должен указывать на *.csproj проекта;
* ProjectItem – отдельные файлы из шаблона. Название внутри тега должно соответствовать названию файла в архиве;
* TargetFileName – название файла после создания проекта по шаблону. Можно создавать папки, для этого надо указать путь через «/» пример на скриншоте. Внутри можно использовать элементы форматирования;
* ReplaceParameters – нужно ли искать в файле элементы форматирования;

2.2.4. Импортируем шаблон в Visual Studio.

Архивируем все файлы шаблона в архив .zip (названия файлов значения не имеют, они будут заменены согласно настройкам, главное чтобы соответствовали указанным в файле метаданных).
Вставляем ахрив по пути (можно не ложить в отдельную папку для языков, но желательно):
%USERPROFILE%\Documents\Visual Studio <version>\Templates\ProjectTemplates
И всё - шаблон готов к использованию после перезагрузки студии.
Баг: если создавать шаблон с открытым файлом из шаблона (или файлом с таким же названием), то может не работать замена элементов форматирования.

image
image
image

Примечание: Важно отметить, что код из шаблона не обязательно должен компилироваться, или даже соответствовать синтаксису, для создания проекта по шаблону.

3. Шаблоны элементов

Создание почти полностью соответствует шаблону проекта. Отличия по порядку создания:

3.1. При изначальном экспорте надо выбрать другой пункт

image
image
image

3.2. В файле с метаданными поменьше тегов и отсутствует тег «Project»:

image

Важно: не все элементы форматирования ведут себя одинаково в шаблонах проектов и шаблонах элементов.
Баг: если создавать шаблон с открытым файлом из шаблона (или файлом с таким же названием), то может не работать замена элементов форматирования.

4. Фрагменты кода (code snippet) в чистой Visual Studio

4.1. Создаем пустой файл и открываем его Visual Studio (желательно создать .xml чтобы подсветка кода работала, но не обязательно).

image

4.2. Вставляем в него стандартный шаблон фрагмента кода и редактируем теги:

<?xml version="1.0" encoding="utf-8"?>
<CodeSnippets xmlns="http://schemas.microsoft.com/VisualStudio/2005/CodeSnippet">
    <CodeSnippet Format="1.0.0">
        <Header>
            <Title></Title>
        <Shortcut></Shortcut>
        <Description></Description>
        <Author></Author>
        <SnippetTypes>
        <SnippetType>SurroundsWith</SnippetType>
            </SnippetTypes>
        </Header>
        <Snippet>
            <Code Language="csharp">
                <![CDATA[]]>
            </Code>
        </Snippet>
    </CodeSnippet>
</CodeSnippets>

Title – Название фрагмента кода, отображаемое пользователю;
Shortcut – сокращение, по которому можно будет быстро вставить фрагмент;
Description – описание фрагмента кода, отображаемое пользователю;
Author – автор, отображается только в отдельном меню. Необязательный тег;
SnippetTypes – теги для фрагмента кода, нужны для сортировки в отдельном меню;
SurroundsWith – указывает, что фрагментом кода можно окружить выделенную область (используются $selected$ и $end$).
4.3. Вставляем код в CDATA[]:

<?xml version="1.0" encoding="utf-8"?>
<CodeSnippets xmlns="http://schemas.microsoft.com/VisualStudio/2005/CodeSnippet">
    <CodeSnippet Format="1.0.0">
        <Header>
            <Title>MySnippet</Title>
        <Shortcut>snippet</Shortcut>
        <Description>snippet</Description>
        <Author>ME</Author>
        <SnippetTypes>
        <SnippetType>SurroundsWith</SnippetType>
            </SnippetTypes>
        </Header>
        <Snippet>
            <Code Language="csharp">
                <![CDATA[var a = "myString";

        $selected$ $end$

                var b = 8;
        ]]>
            </Code>
        </Snippet>
    </CodeSnippet>
</CodeSnippets>

4.4. Импортируем фрагмент кода:

Меняем расширение у файла на .snippet и закидываем по пути:
%USERPROFILE%\Documents\Visual Studio <version>\Code Snippets\Visual C#\My Code Snippets
"My Code Snippets" можно заменить на другое название, или вообще положить прямо в папку языка, это влияет только на то, где надо будет искать фрагмент при долгом способе вставки.
Вот и всё, фрагмент кода готов к использованию после перезагрузки студии. Для использования достаточно вбить сокращение, указанное в теге , или вставить его через сочетание Ctrl+K+S.
Важно: у фрагментов кода, созданных данным способом не будут работать шорткаты с установленным ReSharper, но их всё ещё можно будет использовать через сочетание клавиш.

5. Фрагменты кода (code snippet) с ReSharper

У них документация сильно лучше чем у microsoft, так что можно просто там про это посмотреть:
https://www.jetbrains.com/help/resharper/Reference__Template_Editor.html#general
Но если хочется только тут, то вот минимальный набор:

5.1. Открываем меню фрагментов кода:

image

5.2. Открываем меню создание новых фрагментов кода:

image

5.3. Вводим основные данные по фрагменту кода:

image

  • Shortcut – сокращение, по которому можно будет быстро вставить фрагмент;
  • Description – описание фрагмента кода, отображаемое пользователю;
  • Reformat – форматировать ли фрагмент кода согласно прочим настройкам ReSharper при вставке;
  • Shorten qualified references – нужно ли сокращать ссылки на namespace по возможности при вставке фрагмента кода;
  • Availiability – указывает, где доступен фрагмент кода;
  • Use in - при каких условиях доступен фрагмент кода (при написании шортката, при окружении, и там и там);
  • Mnemonic - ещё более быстрый шорткат;
  • Show in context action - добавляет фрагмент кода в контекстное окно при окружении.

5.4. Создаем нужный фрагмент (описание как работать с параметрами в «дополнительно»):

image

Вот и всё, фрагмент готов к использованию (надо прожать Ctrl+S в меню создания):

image
image
image