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

Статья
08/11/2011

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

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

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

Можно написать метод, который генерирует текст. Примеры.

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(), которые всегда доступны в управляющем блоке. К их числу относятся методы, помогающие делать отступы в выводе и методы для сообщений об ошибках.

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

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

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

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

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

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

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

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

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

Использование модели 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 #>

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

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

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

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

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

Связанные разделы

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

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

Дата	Журнал	Причина
Март 2011	Использование макроса в директиве Assembly.	Обратная связь от клиента.

Март 2011

Использование макроса в директиве Assembly.

Обратная связь от клиента.

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