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

Текстовые шаблоны T4 времени разработки позволяют создавать программный код и другие файлы в проекте Visual Studio.Как правило, шаблоны создаются для того, чтобы менять код, генерируемый на основе данных из модели.Модель — это файл или база данных, которая содержит ключевые сведения о требованиях используемого приложения.

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

Примечание
Модель — это источник данных, описывающий определенный аспект приложения.Это может быть любая форма, любой тип файлов или базы данных.Она не обязательно должна быть представлена определенной формой, например моделью UML или моделью доменного языка.Как правило, модель представлена таблицей или XML-файлом.

Вы, вероятно, уже знакомы с автоматическим созданием кода.Когда вы определяете ресурсы в файле .resx в решении Visual Studio, автоматически создается набор классов и методов.Файл ресурсов облегчает и делает более надежным редактирование ресурсов по сравнению с редактированием классов и методов.Текстовые шаблоны позволяют таким же образом создавать код на основе разработанного вами источника.

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

Создание текстового шаблона T4 во время разработки

Создание шаблона T4 времени разработки в Visual Studio

1. Создайте проект Visual Studio или откройте существующий проект.

   Например, в меню Файл выберите Создать, Проект.

2. Добавьте файл текстового шаблона в проект и присвойте ему имя, которое имеет расширение .tt.

   Чтобы сделать это, в Обозреватель решений, в контекстном меню выберите Добавить проекта, Создать элемент.В диалоговом окне выберите Шаблон текстаДобавление нового элемента из средней области.

   Обратите внимание, что свойство Специальный инструмент этого файла имеет значение TextTemplatingFileGenerator.

3. Откройте файл.Он уже содержит следующие директивы:

   <#@ template hostspecific="false" language="C#" #>
   <#@ output extension=".txt" #>
   

   Если вы добавили шаблон в проект Visual Basic, атрибут языка будет иметь значение "VB".

4. Добавьте в конец файла некоторый текст.Например:

   Hello, world!
   

5. Сохраните файл.

   Может появиться диалоговое окноПредупреждение о безопасности, в котором будет предложено подтвердить запуск шаблона.Нажмите кнопку ОК.

6. В Обозреватель решений разверните узел файла шаблона и найдите файл с расширением .txt.Файл содержит текст, сформированный из шаблона.

   Примечание
   Если ваш проект Visual Basic, то необходимо щелкнуть Показать все файлы чтобы увидеть выходной файл.

Повторное создание кода

Выполнение шаблона и создание дочернего файла будет осуществляться в любом из следующих случаев:

• Правка шаблон, а затем измените фокус на другое окно Visual Studio.

• Сохраните шаблон.

• Нажмите кнопку Преобразовать все шаблоны в меню Построение.В результате будут преобразованы все шаблоны в решении Visual Studio.

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

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

Создание переменного текста

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

Создание текста с использованием программного кода

1. Изменение содержимого файла .tt

   <#@ template hostspecific="false" language="C#" #>
   <#@ output extension=".txt" #>
   <#int top = 10;
   
   for (int i = 0; i<=top; i++) { #>
   The square of <#= i #> is <#= i*i #>
   <# } #>
   

   <#@ template hostspecific="false" language="VB" #>
   <#@ output extension=".txt" #>
   <#Dim top As Integer = 10
   
   For i As Integer = 0 To top
   #>
       The square of <#= i #> is <#= i*i #>
   <#
   Next
   #>
   

2. Сохраните tt-файл и снова откройте созданный txt-файл.В нем будет приведен список квадратов чисел от 0 до 9.

Обратите внимание, что операторы заключены в <#...#>, а одиночные выражения – в <#=...#>.Дополнительные сведения см. в разделе Написание текстового шаблона T4.

При написании создающего кода в Visual Basic директива template должна содержать элемент language="VB".Тип "C#" используется по умолчанию.

Отладка текстового шаблона разработки T4

Отладка текстового шаблона:

• Вставьте элемент кода debug="true" в директиву template.Например:

  <#@ template debug="true" hostspecific="false" language="C#" #>

• Установите точки останова в шаблоне, осуществляется так же, как и для обычного кода.

• Выберите в контекстном меню Отладить шаблон T4 файла текстового шаблона в обозревателе решений.

Шаблон выполняется и останавливается в точках останова.Можно проверить переменные и с помощью кода обычным способом.

Совет

debug="true" выполняет сопоставление кода, созданного для более точного к текстовому шаблону, путем вставки несколько директив нумерации линии в сформированном коде.Если оставить его, то точки останова могут перестать выполнить в неверном состоянии. Однако можно оставить предложение в директивы шаблона, даже если пользователь не отладки.Это приводит к очень маленькое удаление только в производительности.

Создающий код или ресурсы для решения

Можно автоматически создавать программные файлы, содержимое которых будет зависеть от модели.Модель – это входная информация, такая как база данных, файл конфигурации, модель языка UML или DSL либо другой источник.Обычно на основе одной модели создают несколько программных файлов.С этой целью для каждого программного файла создают файл шаблона, так чтобы все эти шаблоны считывались одной моделью.

Создание программного кода или ресурсов

1. Измените директиву вывода, чтобы создавался файл соответствующего типа, такого как cs, vb, resx или xml.

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

                     <#@ template debug="false" hostspecific="false" language="C#" #>
   <#@ output extension=".cs" #>
   <# var properties = new string [] {"P1", "P2", "P3"}; #>
   class MyGeneratedClass {
   <# 
     foreach (string propertyName in properties)
     { #>
     private int <#= propertyName #> = 0;
   <# } #>
   }
   

   <#@ template debug="false" hostspecific="false" language="VB" #>
   <#@ output extension=".cs" #>
   <# Dim properties = {"P1", "P2", "P3"} #>
   class MyGeneratedClass {
   <# 
      For Each propertyName As String In properties
   #>
     private int <#= propertyName #> = 0;
   <#
      Next
   #>
   }
   

3. Сохраните этот файл и взгляните на содержимое созданного файла — он должен содержать следующий код:

   class MyGeneratedClass {
     private int P1 = 0; 
     private int P2 = 0;
     private int P3 = 0;
   }
   

Создание кода и сгенерированного текста

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

Существует два варианта предыдущего примера.В одном из них создающий код написан на языке C#.В другом — в Visual Basic.Однако текст в обоих примерах создается одинаковый, этот текст представляет собой класс C#.

Аналогично шаблон Visual C# можно использовать для создания кода на любом языке.Не обязательно создавать текст на каком-то конкретном языке, и не обязательно этот текст должен являться программным кодом.

Структурирование текстовых шаблонов

Код шаблона рекомендуется разделять на две части.

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

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

• Создание текста (foreach(...){...} в данном примере), где используются значения переменных.

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

Чтение файлов или других источников

Для доступа к файлу или базе данных модели код шаблона может использовать сборки, например System.XML.Для получения доступа к этим сборкам необходимо вставить директивы, например такие:

<#@ assembly name="System.Xml.dll" #>
<#@ import namespace="System.Xml" #>
<#@ import namespace="System.IO" #>

Директива assembly делает заданную сборку доступной для кода проекта, так же как раздел References проекта Visual Studio.Нет необходимости включать ссылку на файл System.dll, ссылка на который создается автоматически.Директива import позволяет использовать типы без использования их полных имен аналогично директиве using обычного программного файла.

Например, после импорта System.IO можно написать:

          <# var properties = File.ReadLines("C:\\propertyList.txt");#>
...
<# foreach (string propertyName in properties) { #>
...

<# For Each propertyName As String In 
             File.ReadLines("C:\\propertyList.txt")
#>

Открытие файла с именем относительного пути

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

<#@ template debug="false" hostspecific="true" language="C#" #>

Затем можно написать, к примеру, следующее:

<# string fileName = this.Host.ResolvePath("filename.txt");
  string [] properties = File.ReadLines(filename);
#>
...
<#  foreach (string propertyName in properties { #>
...

<# Dim fileName = Me.Host.ResolvePath("propertyList.txt")
   Dim properties = File.ReadLines(filename)
#>
...
<#   For Each propertyName As String In properties
...
#>

Кроме того, можно использовать this.Host.TemplateFile, определяющее имя текущего файла шаблона.

Типом this.Host (Me.Host в VB) является Microsoft.VisualStudio.TextTemplating.ITextTemplatingEngineHost.

Получение данных из Visual Studio

Для использования, предоставляемых услуг в Visual Studio, задайте для атрибута hostSpecific и загрузить сборку EnvDTE.Затем можно использовать IServiceProvider.GetCOMService() для доступа к DTE и других служб.Например:

<#@ template hostspecific="true" language="C#" #>
<#@ output extension=".txt" #>
<#@ assembly name="EnvDTE" #>
<#
  IServiceProvider serviceProvider = (IServiceProvider)this.Host;
  EnvDTE.DTE dte = (EnvDTE.DTE) serviceProvider.GetCOMService(typeof(EnvDTE.DTE));
#>

Number of projects in this VS solution:  <#= dte.Solution.Projects.Count #>

Совет
Текстовый шаблон выполняется в своем собственном домене приложений и служб, получить доступ, маршалировать.В этом обстоятельстве, GetCOMService() более чем GetService()надежно.

Автоматическое повторное создание кода

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

Если исходная модель изменяется, необходимо заново выполнить все шаблоны в решении.Чтобы сделать это Преобразовать все шаблоны вручную, выберите в меню Построение.

Если установлен Visual Studio пакет SDK визуализации и моделирования, можно сделать так, чтобы каждый раз при выполнении построения все шаблоны преобразовывались автоматически.Для этого откройте файл проекта (с расширением csproj или vbproj) в текстовом редакторе и добавьте в конец файла после всех остальных операторов <import> следующие операторы:

<Import Project="$(MSBuildExtensionsPath)\Microsoft\VisualStudio\v11.0\TextTemplating\Microsoft.TextTemplating.targets" />
<PropertyGroup>
   <TransformOnBuild>true</TransformOnBuild>
   <!-- Other properties can be inserted here -->
</PropertyGroup>

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

Отчетность по ошибкам

Для вывода сообщений об ошибках и предупреждающих сообщений в окне сообщения об ошибках Visual Studio можно использовать следующие методы:

Error("An error message");
Warning("A warning message");

Преобразование существующего файла в шаблон

Удобной особенностью шаблонов является то, что они подобны создаваемым на их основе файлам, но дополнительно содержат некоторый программный код.Поэтому удобен такой способ создания шаблона.Создайте обычный файл в качестве прототипа будущего шаблона, например файл Visual C#, а затем включите в него создающий код, обеспечивающий варьирование содержимого результирующих файлов.

Преобразование существующего файла в шаблон времени разработки

1. Добавьте файл типа, который необходимо создать, в проект Visual Studio. Это может быть файл .cs, .vb или .resx.

2. Протестируйте новый файл, чтобы убедиться, что он работает.

3. В обозревателе решений смените расширение имени файла на .tt.

4. Проверьте следующие свойства файла .tt:

   Пользовательский инструмент =	TextTemplatingFileGenerator
   Действие при построении =	None

5. В начало файла вставьте следующие строки:

   <#@ template debug="false" hostspecific="false" language="C#" #>
   <#@ output extension=".cs" #>
   

   Если требуется записать в шаблон создающий код на Visual Basic, задайте для атрибута language значение "VB" вместо "C#".

   Атрибуту extension присвойте расширение имени файла для того типа файлов, которые требуется создать, например .cs, .resx или .xml.

6. Сохраните файл.

   Будет создан дочерний файл с заданным расширением.Его свойства будут установлены в соответствии с типом файла.Например, свойство Действие при построении файла cs будет иметь значение Компилировать.

   Убедитесь, что созданный файл имеет то же содержимое, что и исходный файл.

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

Рекомендации по созданию кода

См. раздел Рекомендации по написанию текстовых шаблонов T4.

Следующие шаги

См. также

Основные понятия

Рекомендации по написанию текстовых шаблонов T4