Создание пользовательских обработчиков директив шаблона текста T4

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

Чтобы создать пользовательский обработчик директив, создайте класс, наследующий либо от DirectiveProcessor, либо от RequiresProvidesDirectiveProcessor.

Разница между этими двумя заключается в том, что DirectiveProcessor реализует минимальный интерфейс, необходимый для получения параметров от пользователя и создания кода, создающего выходной файл шаблона. RequiresProvidesDirectiveProcessor реализует шаблон проектирования требует/предоставляет. RequiresProvidesDirectiveProcessor обрабатывает два специальных параметра: requires и provides. Например, настраиваемый обработчик директив может принимать имя файла от пользователя, открывать и читать файл, а затем хранить текст файла в переменной, которая называется fileText. Подкласс RequiresProvidesDirectiveProcessor класса может принимать имя файла от пользователя в качестве значения requires параметра, а также имя переменной, в которой будет храниться текст в качестве значения provides параметра. Этот обработчик открывает и считывает файл, а затем сохраняет текст файла в указанной переменной.

Перед вызовом пользовательского обработчика директив из текстового шаблона в Visual Studio необходимо зарегистрировать его.

Дополнительные сведения о добавлении ключа реестра см. в разделе "Развертывание пользовательского обработчика директив".

Пользовательские директивы

Настраиваемая директива выглядит следующим образом:

<#@ MyDirective Processor="MyDirectiveProcessor" parameter1="value1" ... #>

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

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

Ниже приведены некоторые примеры пользовательских процессоров директив:

• Обработчик директив для возврата данных из базы данных, которая принимает имя пользователя и пароль в качестве параметров.

• Обработчик директив для открытия и чтения файла, который принимает имя файла в качестве параметра.

Основные части пользовательского обработчика директив

Для разработки обработчика директив необходимо создать класс, наследующий либо от DirectiveProcessor, либо от RequiresProvidesDirectiveProcessor.

Ниже приведены наиболее важные DirectiveProcessor методы, которые необходимо реализовать.

• bool IsDirectiveSupported(string directiveName) — Верните true, если ваш обработчик директив может обработать именованную директиву.

• void ProcessDirective (string directiveName, IDictionary<string, string> arguments) — движок шаблонов вызывает этот метод для каждого вхождения директивы в шаблоне. Обработчик должен сохранить результаты.

После всех вызовов ProcessDirective() обработчик шаблонов вызовет следующие методы:

• string[] GetReferencesForProcessingRun() — возвращает имена сборок, необходимых коду шаблона.

• string[] GetImportsForProcessingRun() — возвращает пространства имен, которые можно использовать в коде шаблона.

• string GetClassCodeForProcessingRun() — вернуть код методов, свойств и других деклараций, которые может использовать код шаблона. Самый простой способ сделать это — создать строку, содержащую код C# или Visual Basic. Чтобы сделать обработчик директив способным вызываться из шаблона, использующего любой язык CLR, можно создать инструкции в виде дерева CodeDom, а затем вернуть результат сериализации дерева на языке, используемом шаблоном.

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

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

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