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

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

• <# 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.