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

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

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

Разница между этими двумя заключается в том, что DirectiveProcessor реализует минимальный интерфейс, необходимый для получения параметров от пользователя и создания кода, создающего выходной файл шаблона. RequiresProvidesDirectiveProcessor реализует шаблон конструктора . RequiresProvidesDirectiveProcessor обрабатывает два специальных параметра и requiresprovides. Например, настраиваемый обработчик директив может принимать имя файла от пользователя, открывать и читать файл, а затем хранить текст файла в переменной, которая называется 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.