Директива Template T4

Как правило, текстовый шаблон T4 в Visual Studio начинается с директивы template, которая задает способ обработки шаблона. В каждом текстовом шаблоне и файлах, которые он содержит, может присутствовать только одна директива шаблона.

Общие сведения о создании текстовых шаблонов см. в разделе Написание текстового шаблона T4.

Применение директивы Template

<#@ template [language="VB"] [compilerOptions="options"] [culture="code"] [debug="true"] [hostspecific="true"] [inherits="templateBaseClass"] [visibility="internal"] [linePragmas="false"] #>

Директива template имеет несколько атрибутов, позволяющих задавать разные аспекты преобразования. Ни один атрибут не является обязательным.

атрибут compilerOptions

• Пример:
  compilerOptions="optimize+"

• Допустимые значения:
  Любые допустимые параметры компилятора. Дополнительные сведения см. в разделах Параметры компилятора C#, упорядоченные по категориям и Параметры компилятора Visual Basic по категориям.

  Игнорируется для шаблонов времени выполнения (предварительно обработанных).

Эти параметры применяются, если шаблон преобразован в Visual C# или Visual Basic и компилируется полученный код.

атрибут culture

• Пример:
  culture="de-CH"

• Допустимые значения:
  "", инвариантные язык и региональные параметры, используемые по умолчанию.

  Язык и региональные параметры задаются как строка в форме xx-XX. Например: en-US, ja-JP, de-CH, de-DE. Дополнительные сведения см. в разделе CultureInfo.

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

атрибут debug

• Пример.

  debug="true"
  

• Допустимые значения:
  true, false. Значение по умолчанию — false.

Если атрибут debug имеет значение true, промежуточный файл кода содержит сведения, позволяющие отладчику точнее определить положение прерывания или исключения в шаблоне.

Промежуточный файл кода для шаблонов времени разработки записывается в каталог %TEMP%.

Для выполнения шаблона времени разработки в отладчике сохраните текстовый шаблон, затем откройте контекстное меню текстового шаблона в обозревателе решений и выберите команду Отладить шаблон T4.

атрибут hostspecific

• Пример.

  hostspecific="true"
  

• Допустимые значения:
  true, false, trueFromBase. Значение по умолчанию — false.

Если задать для этого атрибута значение true, свойство с именем Host будет добавлено в класс, сгенерированный текстовым шаблоном. Это свойство представляет собой ссылку на узел модуля преобразования и объявляется как ITextTemplatingEngineHost. Если определено пользовательское основное приложение, можно выполнить его приведение к типу пользовательского основного приложения.

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

Когда свойство hostspecific имеет значение true и вы используете Visual Studio, можно привести this.Host к типу IServiceProvider для доступа к функциям Visual Studio. Кроме того, можно воспользоваться Host.ResolvePath(filename) для получения абсолютного пути к файлу в проекте. Пример.

<#@ template debug="false" hostspecific="true" language="C#" #>
<#@ output extension=".txt" #>
<#@ assembly name="EnvDTE" #>
<#@ import namespace="EnvDTE" #>
<#@ import namespace="System.IO" #>
<# // Get the Visual Studio API as a service:
 DTE dte = ((IServiceProvider)this.Host).GetCOMService(typeof(DTE)) as DTE;  
#>
Number of projects in this solution: <#=  dte.Solution.Projects.Count #>

<#
 // Find a path within the current project:
 string myFile = File.ReadAllText(this.Host.ResolvePath("MyFile.txt"));
#>
Content of myFile is:
<#= myFile #>

Если атрибуты inherits и hostspecific используются совместно, укажите host="trueFromBase" в производном классе и host="true" в базовом классе. Это позволит избежать двойного определения свойства Host в созданном коде.

атрибут language

• Пример.
  language="VB"

• Допустимые значения:
  C# (по умолчанию)

  VB

Атрибут language задает язык (Visual Basic или Visual C#) для использования в исходном коде в блоках инструкций и выражений. Этот язык будет использоваться в промежуточном файле кода, из которого создаются выходные данные. Этот язык не связан с языком, создаваемым шаблоном, который может быть представлен любым видом текста.

Пример.

<#@ template language="VB" #>
<#@ output extension=".txt" #>
Squares of numbers:
<#
  Dim number As Integer
  For number = 1 To 4
#>
  Square of <#= number #> is <#= number * number #>
<#
  Next number
#>

атрибут inherits

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

Наследование в текстовом шаблоне времени выполнения (предварительно обработанном)

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

Если атрибут inherits не задан, базовый и производный классы создаются из текстового шаблона. При задании атрибута inherits создается только производный класс. Можно создать базовый класс вручную, однако он должен предоставлять методы, используемые производным классом.

Как правило, в качестве базового класса указывается другой предварительно обработанный шаблон. Базовый шаблон предоставляет общие блоки текста, которые могут чередоваться с текстом из производных шаблонов. Можно использовать блоки функций класса <#+ ... #>, чтобы определить методы, содержащие фрагменты текста. Например, можно поместить структуру выходного текста в базовый шаблон и предоставить виртуальные методы, которые могут переопределяться в производных шаблонах:

• Текстовый шаблон времени выполнения (предварительно обработанный) BaseTemplate.tt:

  This is the common header.
  <# 
    SpecificFragment1(); 
  #>
  A common central text.
  <# 
    SpecificFragment2(); 
  #>
  This is the common footer.
  <#+ 
    // Declare abstract methods
    protected virtual void SpecificFragment1() { }
    protected virtual void SpecificFragment2() { }
  #>
  

• Текстовый шаблон времени выполнения (предварительно обработанный) DerivedTemplate1.tt:

  <#@ template language="C#" inherits="BaseTemplate" #>
  <# 
    // Run the base template:
    base.TransformText();
  #>
  <#+
  // Provide fragments specific to this derived template:
  protected override void SpecificFragment1()
  {
  #>
     Fragment 1 for DerivedTemplate1
  <#+
  }
  protected override void SpecificFragment2()
  {
  #>
     Fragment 2 for DerivedTemplate1
  <#+
  }
  #>
  

• Код приложения для вызова DerivedTemplate1:

  Console.WriteLine(new DerivedTemplate().TransformText());
  

• Полученные выходные данные:

  This is the common header.
     Fragment 1 for DerivedTemplate1
  A common central text.
     Fragment 2 for DerivedTemplate1
  This is the common footer.
  

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

Кроме того, в качестве базового класса можно использовать обычный, созданный вручную класс. Базовый класс должен предоставлять методы, используемые производным классом.

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

Если атрибуты inherits и hostspecific используются совместно, укажите hostspecific="trueFromBase" в производном классе и host="true" в базовом классе.Это позволит избежать двойного определения свойства Host в созданном коде.

Наследование в текстовом шаблоне времени разработки

Текстовый шаблон времени разработки — это файл, параметру Специальный инструмент которого задано значение TextTemplatingFileGenerator. Этот шаблон позволяет создать выходной файл кода или текста, формирующего часть проекта Visual Studio. При создании выходного файла шаблон сначала преобразуется в промежуточный файл программного кода, который обычно не видно пользователю. Атрибут inherits задает базовый класс для данного промежуточного кода.

Для текстового шаблона времени разработки можно задать любой базовый класс, наследуемый от TextTransformation. Воспользуйтесь директивой <#@assembly#> для загрузки сборки или проекта, содержащего базовый класс.

Дополнительные сведения см. в разделе "Inheritance in Text Templates" (Наследование в текстовых шаблонах) в блоге Гарета Джонса (Gareth Jones).

Атрибут LinePragmas

• Пример.
  linePragmas="false"

• Допустимые значения:
  true (по умолчанию)

  false

Если для этого атрибута установлено значение false, удаляются теги, задающие номера строк в созданном коде. Это означает, что компилятор сообщает о любых ошибках с указанием номеров строк созданного кода. Таким образом расширяются возможности отладки, позволяя выбирать отладку текстового шаблона или созданного кода.

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

Атрибут Visibility

• Пример.
  visibility="internal"

• Допустимые значения:
  public (по умолчанию)

  internal

В текстовом шаблоне времени выполнения задает атрибут видимости созданного класса. По умолчанию класс является частью открытого API кода, но если задать значение visibility="internal", только ваш код сможет использовать класс, создающий текст.