Управляющие блоки текстовых шаблонов

Статья
08/25/2023

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

<# Standard control blocks #> может содержать операторы;
<#= Expression control blocks #> может содержать выражения;
<#+ Class feature control blocks #> может содержать методы, поля и свойства.

Стандартные блоки управления

Стандартные блоки управления содержат операторы. Например, следующий стандартный блок получает имена всех атрибутов в документе XML.

<#@ assembly name="System.Xml.dll" #>
<#@ import namespace="System.Xml" #>

<#
    List<string> allAttributes = new List<string>();
    XmlDocument xDoc = new XmlDocument();
    xDoc.Load(@"E:\CSharp\Overview.xml");
    XmlAttributeCollection attributes = xDoc.Attributes;
    if (attributes.Count > 0)
    {
       foreach (XmlAttribute attr in attributes)
       {
           allAtributes.Add(attr.Name);
       }
     }
#>

В составной оператор, такой как if или for, можно вставить обычный текст. Например, указанный фрагмент создает строку вывода в каждой итерации цикла.

<#
       foreach (XmlAttribute attr in attributes)
       {
#>
Found another one!
<#
           allAtributes.Add(attr.Name);
       }
#>

Предупреждение

Всегда используйте {...} для разделителя вложенных инструкций, содержащих внедренный обычный текст. Следующий пример может не работать должным образом.

<# if (ShouldPrint) #> Some text. -- WRONG

Вместо этого следует включить {фигурные скобки} следующим образом.


<#
 if (ShouldPrint)
 {   //  "{" REQUIRED
#>
Some text.
<#
 }
#>

Блок управления выражениями

Блоки управления выражениями используются для кода, предоставляющего строки для записи в выходной файл. Например, в приведенном выше примере можно выводить имена атрибутов в выходной файл, изменив блок кода следующим образом.

<#
    XmlDocument xDoc = new XmlDocument();
    xDoc.Load(@"E:\CSharp\Overview.xml");
    XmlAttributeCollection attributes = xDoc.Attributes;
    if (attributes != null)
    {
       foreach (XmlAttribute attr in attributes)
       {
#><#= attr.Name #><#
       }
    }
#>

Блок управления возможностями класса

Блоки управления возможностями класса позволяют добавлять методы, свойства, поля или даже вложенные классы в текстовый шаблон. Чаще всего блоки возможностей класса используют для предоставления вспомогательных возможностей для кода в других частях текстового шаблона. Например, следующий блок возможностей класса преобразует в прописную первую букву имени атрибута (или, если имя содержит пробелы, преобразует в прописные первые буквы каждого слова).

<#@ import namespace="System.Globalization" #>

<#+
    private string FixAttributeName(string name)
    {
        return CultureInfo.CurrentCulture.TextInfo.ToTitleCase(name);
    }
#>

Примечание.

За блоком управления возможностями класса не должны следовать стандартные управляющие блоки в одном файле шаблона. Однако это ограничение не применяется к результату использования директив <#@include#>. Каждый включенный файл может иметь стандартные блоки, за которыми следуют блоки возможностей класса.

Можно создать возможность, которая создает выходные данные путем внедрения текста и блоков выражений в блок управления возможностями класса. Например:

<#+
    private void OutputFixedAttributeName(string name)
    {
#>
 Attribute:  <#= CultureInfo.CurrentCulture.TextInfo.ToTitleCase(name) #>
<#+  // <<< Notice that this is also a class feature block.
    }
#>

Эту возможность можно вызвать из стандартного блока или из другого блока возможностей класса.

<# foreach (Attribute attribute in item.Attributes)
{
  OutputFixedAttributeName(attribute.Name);
}
#>

Использование блоков управления

Весь код во всех стандартных блоках управления и блоках управления выражениями в одном шаблоне (включая весь код во включенных шаблонах) объединяется для образования метода TransformText() созданного кода. (Дополнительные сведения о том, как включить другие текстовые шаблоны с директивой include , см . в директивах шаблонов текста T4.)

При использовании блоков управления необходимо помнить о следующих аспектах.

Язык. В текстовом шаблоне можно использовать код C# или Visual Basic. Языком по умолчанию является C#, но можно указать Visual Basic с помощью параметра language директивы template. (Дополнительные сведения об директиве template см . в директивах шаблона текста T4.)

Язык, который вы используете в блоках управления, не связан с языком или форматом текста, создаваемого в текстовом шаблоне. Можно создать шаблон C#, используя код Visual Basic, и наоборот.

Можно использовать только один язык в данном текстовом шаблоне, сюда относятся все текстовые шаблоны, включаемые с помощью директивы include.
Локальные переменные. Поскольку весь код в стандартных блоках и блоках управления выражениями в текстовом шаблоне создается как один метод, необходимо убедиться в отсутствии конфликтов с именами локальных переменных. Если вы включаете другие текстовые шаблоны, необходимо убедиться в том, что имена переменных уникальны во всех включаемых шаблонах. Один из способов — добавление к имени каждой локальной переменной строки, идентифицирующей текстовый шаблон, в котором она объявлена.

Также можно рекомендовать инициализацию локальных переменных допустимыми значениями при их объявлении, особенно при включении нескольких текстовых шаблонов.
Вложение блоков управления. Вложение блоков управления не поддерживается. Необходимо всегда закрывать текущий блок управления перед открытием следующего. Например, ниже показано, как вывести некоторый текст в блоке выражения в составе стандартного блока управления.
```
<#
int x = 10;
while (x-- > 0)
{
#>
<#= x #>
<# } #>
```
Рефакторинг. Чтобы сделать текстовые шаблоны краткими и удобными для восприятия, настоятельно рекомендуется избегать повторяющихся участков кода, разлагая повторно используемый код на вспомогательные возможности в блоках возможностей класса или создав собственный класс текстового шаблона, который наследует от класса Microsoft.VisualStudio.TextTemplating.TextTransformation.

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