Директива Template T4

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

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

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

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

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

атрибут compilerOptions

Пример:

compilerOptions="optimize+"

Допустимые значения:

Любые допустимые параметры компилятора.

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

Эти параметры применяются при преобразовании шаблона в 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 (по умолчанию)

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

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

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

атрибут hostspecific

Пример:

hostspecific="true"

Допустимые значения:

true

false (по умолчанию)

trueFromBase

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

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

true Когда hostspecific вы используете 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" #>
<#@ import namespace="Microsoft.VisualStudio.TextTemplating" #>
<# // 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

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

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

Можно использовать наследование между текстовыми шаблонами времени выполнения для создания базового шаблона с несколькими производными вариантами. Шаблоны времени выполнения — это шаблоны, у которых свойство Custom Tool имеет значение 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 задает базовый класс для данного промежуточного кода.

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

Дополнительные сведения см. в разделе "Наследование в текстовых шаблонах" в блоге Гарет Джонса.

Атрибут linePragmas

Пример:

linePragmas="false"

Допустимые значения:

true (по умолчанию)

false

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

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

Атрибут видимости

Пример:

visibility="internal"

Допустимые значения:

public (по умолчанию)

internal

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