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

Статья
02/20/2013

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

<#
    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 также создают строго типизированные классы, отражающие структуру модели.Дополнительные сведения см. в разделе Создание кода из доменного языка.

Использование модели 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
Преобразуйте данные в форму доменного языка.	Создание кода из доменного языка
Напишите обработчики директив для преобразования собственных источников данных.	Настройка преобразования текста T4

Share via