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

Статья
06/09/2015

Текстовый шаблон содержит текст, который будет создан на его основе. Например, шаблон, создающий веб-страницу, будет содержать "<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" #>

Список макросов см. в разделе Макросы для команд и свойств построения.

В предварительно преобразованном текстовом шаблоне директива assembly не производит никакого эффекта.

Для получения дополнительной информации см. Директива Assembly T4.

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

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

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

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

Для получения дополнительной информации см. Директива Import T4.

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

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

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

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

Для получения дополнительной информации см. Директива Include T4.

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

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

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

Для получения дополнительной информации см. Служебные методы для текстовых шаблонов.

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

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

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

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

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

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

Редактирование файла модели в схеме или форме. Инструменты DSL включает средства, которые позволяют редактировать модель как схему или форму Windows. Это упрощает обсуждение модели с пользователями созданного приложения. Инструменты DSL также создает набор строго типизированных классов, отражающих структуру модели. Для получения дополнительной информации см. Generating Code from a Domain-Specific Language.

Использование модели UML. Можно создать код на основе модели UML. Это обеспечивает преимущество редактирования модели в качестве схемы в рамках привычной нотации. Кроме того, вам не потребуется разрабатывать схему. Для получения дополнительной информации см. Практическое руководство. Создание файлов из модели UML.

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

В текстовом шаблоне времени разработки для ссылки на файл в расположении, относительном к текстовому шаблону, используется метод 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 #>

Можно также получить другие службы, предоставляемые узлом. Для получения дополнительной информации см. Accessing Visual Studio or other Hosts from a Template.

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

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

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

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

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

См. также

Задача	Раздел
Создание шаблона.	Рекомендации по написанию текстовых шаблонов T4
Создание текста с помощью программного кода.	Написание текстового шаблона T4
Создание файлов в решении Visual Studio.	Создание кода во время разработки с помощью текстовых шаблонов T4
Запуск создания текста за пределами Visual Studio.	Создание файлов с помощью служебной программы TextTransform
Преобразование данных в форме доменного языка.	Generating Code from a Domain-Specific Language
Написание процессоров директив для преобразования собственных источников данных.	Настройка преобразования текста T4

Поделиться через