Share via

Написание текстового шаблона T4

  • Статья

Текстовый шаблон содержит текст, который будет создан на его основе. Например, шаблон, создающий веб-страницу, будет содержать html<>..." и все остальные стандартные части HTML-страницы. Вставленными в шаблон являются блоки управления, которые являются фрагментами кода программы. Блоки управления обеспечивают варьирующиеся значения и обеспечивают условность и повторяемость текста.

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

Текстовые шаблоны состоят из следующих частей.

  • Директивы — элементы, управляющие обработкой шаблона.

  • Текстовые блоки — содержимое, скопированное непосредственно в выходные данные.

  • Блоки управления — программный код, который вставляет значения переменных в текст и управляет условными или повторяющимися частями текста.

Чтобы попробовать примеры в этом разделе, скопируйте их в файл шаблона, как описано в разделе "Создание кода во время разработки" с помощью шаблонов текста T4. После редактирования файла шаблона сохраните его, а затем проверьте выходной TXT-файл .

Директивы

Директивы текстовых шаблонов предоставляют общие инструкции модулю текстовых шаблонов в отношении порядка создания кода преобразования и выходного файла.

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

<#@ output extension=".txt" #>

Дополнительные сведения об директивах см. в директивах шаблонов T4.

Текстовые блоки

Текстовый блок вставляет текст непосредственно в выходной файл. Для текстовых блоков нет особых правил форматирования. Например, следующий текстовый шаблон создаст текстовый файл со словом "Hello":

<#@ output extension=".txt" #>
Hello

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

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

<#@ template language="VB" #>

Язык, на котором вы будете писать код в блоках управления, не связан с языком создаваемого текста.

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

Стандартный блок управления представляет собой раздел программного кода, который создает часть выходного файла.

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

Например, следующий блок управления и текстовый блок создают выходной файл, который содержит строку "0, 1, 2, 3, 4 Hello!":

<#
    for(int i = 0; i < 4; i++)
    {
        Write(i + ", ");
    }
    Write("4");
#> Hello!

Вместо использования явных операторов Write(), можно чередовать текст и код. В следующем примере печатается "Hello!" четыре раза:

<#
    for(int i = 0; i < 4; i++)
    {
#>
Hello!
<#
    }
#>

Можно вставить блок текста в любое место кода, где допускается вставка оператора Write();.

Примечание.

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

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

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

Блоки управления выражениями разделяются символами <#= ... #>

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

<#= 2 + 3 #>

Обратите внимание, что открывающий символ имеет три символа "<#=".

Это выражение может включать любую переменную в области. Например, этот блок печатает строки цифр:

<#@ output extension=".txt" #>
<#
    for(int i = 0; i < 4; i++)
    {
#>
This is hello number <#= i+1 #>: Hello!
<#
    }
#>

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

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

Блоки управления возможностями класса разделяются символами <#+ ... #>.

Например, следующий файл шаблона объявляет и использует метод:

<#@ output extension=".txt" #>
Squares:
<#
    for(int i = 0; i < 4; i++)
    {
#>
    The square of <#= i #> is <#= Square(i+1) #>.
<#
    }
#>
That is the end of the list.
<#+   // Start of class feature block
private int Square(int i)
{
    return i*i;
}
#>

Возможности класса необходимо помещать в конец файла, в котором они написаны. Однако можно включить файл (используя <#@include#>), содержащий возможность класса, даже если за директивой include следует текст и стандартные блоки.

Дополнительные сведения о блоках управления см. в разделе "Блоки элементов управления текстовым шаблоном".

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

Вы можете написать метод, создающий текст. Например:

List of Squares:
<#
   for(int i = 0; i < 4; i++)
   {  WriteSquareLine(i); }
#>
End of list.
<#+   // Class feature block
private void WriteSquareLine(int i)
{
#>
   The square of <#= i #> is <#= i*i #>.
<#+
}
#>

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

Использование внешних определений

Сборки

Блоки кода шаблона могут использовать типы, определенные в наиболее часто используемых сборках .NET, таких как System.dll. Кроме того, можно добавить ссылку на другие сборки .NET или ваши собственные. Можно предоставить путь или строгое имя сборки:

<#@ assembly name="System.Xml" #>

Необходимо использовать абсолютные пути или стандартные имена макросов в пути. Например:

<#@ assembly name="$(SolutionDir)library\MyAssembly.dll" #>

Директива сборки не действует в предварительно обработанном текстовом шаблоне.

Дополнительные сведения см. в директиве T4 Assembly.

Пространства имен

Директива import соответствует выражению using в C# или выражению imports в Visual Basic. Она позволяет ссылаться на типы в коде, не используя полное имя:

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

Число используемых директив assembly и import не ограничено. Их нужно размещать до блоков управления и текста.

Дополнительные сведения см. в директиве импорта T4.

Включение кода и текста

Директива include вставляет текст из другого файла шаблона. Например, эта директива вставляет содержимое файла test.txt:

<#@ include file="c:\test.txt" #>

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

Дополнительные сведения см. в директиве T4 Include.

Служебные методы

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

Кроме того, вы можете создать собственный набор служебных методов.

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

Преобразование данных и моделей

Наиболее полезная сфера применения текстовых шаблонов — создание материалов на основе содержимого источника, такого как модель, база данных или файл данных. Шаблон извлекает данные и изменяет их формат. Коллекция шаблонов может преобразовать подобный источник в несколько файлов.

Существует несколько способов считывания исходного файла.

Чтение файла в текстовом шаблоне. Это самый простой способ получения данных в шаблоне:

<#@ import namespace="System.IO" #>
<# string fileContent = File.ReadAllText(@"C:\myData.txt"); ...

Загрузите файл в виде навигации модели. Более эффективный способ — это чтение данных как модели, по которой может перемещаться код текстового шаблона. Например, можно загрузить XML-файл и выполнять навигацию по этому файлу с помощью выражений XPath. Можно также использовать xsd.exe для создания набора классов, с помощью которых можно считывать XML-данные.

Измените файл модели в схеме или форме. Инструменты языка для конкретного домена предоставляют средства, позволяющие изменять модель в виде схемы или формы Windows. Это упрощает обсуждение модели с пользователями созданного приложения. Инструменты языка для конкретного домена также создают набор строго типизированных классов, которые отражают структуру модели. Дополнительные сведения см. в разделе "Создание кода на языке для конкретного домена".

Относительные пути файлов в шаблонах времени разработки

В текстовом шаблоне времени разработки, если вы хотите ссылаться на файл в расположении относительно текстового шаблона, используйте this.Host.ResolvePath(). Кроме того, необходимо задать выражение hostspecific="true" в директиве template:

<#@ template hostspecific="true" language="C#" #>
<#@ output extension=".txt" #>
<#@ import namespace="System.IO" #>
<#
 // Find a path within the same project as the text template:
 string myFile = File.ReadAllText(this.Host.ResolvePath("MyFile.txt"));
#>
Content of MyFile.txt is:
<#= myFile #>

Можно также получить другие службы, предоставляемые узлом. Дополнительные сведения см. в разделе "Доступ к Visual Studio" или другим узлам из шаблона.

Текстовые шаблоны времени разработки выполняются в отдельном домене приложения

Следует учитывать, что текстовый шаблон во время разработки выполняется в домене приложения, отдельном от основного приложения. В большинстве случаев это неважно, однако вы можете столкнуться с ограничениями в некоторых сложных случаях. Например, если нужно передать данные в шаблон или из него, используя отдельную службу, эта служба должна предоставить сериализуемый API.

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

Редактирование шаблонов

Специализированные редакторы текстовых шаблонов можно загрузить из каталога диспетчера расширений в Интернете. В меню "Сервис" щелкните "Диспетчер расширений". Щелкните онлайн-коллекцию и используйте средство поиска.

Связанный контент