Директива Template T4

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

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

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

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

Директива 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. Дополнительные сведения см. в разделе System.Globalization.CultureInfo.

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

атрибут debug

• Пример:

  debug="true"
  

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

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

Чтобы запустить отладчик в определенный момент выполнения шаблона, вставьте вызов типа Launch. Чтобы прервать выполнение в определенные моменты, вставьте вызов типа Break. Пример.

<#@ template debug="true" language="C#" #>
<#@ output extension=".txt" #>
Output something.
<# 
 // Break here:
 System.Diagnostics.Debugger.Launch();  
#>
Output more.
<#
 // Break here also:
 System.Diagnostics.Debugger.Break();  
#>
Output more.

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

атрибут hostspecific

• Пример:

  hostspecific="true"
  

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

Если задать для этого атрибута значение true, свойство с именем Host будет добавлено в класс, сгенерированный текстовым шаблоном. Это свойство представляет собой ссылку на узел модуля преобразования и объявляется как Microsoft.VisualStudio.TextTemplating.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).GetService(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 #>

атрибут language

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

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

  VB

  (Значения VBv3.5 и C#v3.5 более не поддерживаются в данном выпуске, они будут интерпретироваться как VB и C#.)

Атрибут 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.
  

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

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

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

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

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

Дополнительные сведения см. в посте Inheritance in Text Templates в блоге Гэррета Джонса.

Журнал изменений

Дата	Журнал	Причина
Март 2011	Отделен от родительского раздела. Добавлены сведения о compilerOptions. Добавлена ссылка на пост о наследовании текстовых шаблонов в блоге.	Улучшение информации.