Creating Custom Text Template Directive Processors

The text template transformation process takes a text template file as the input and produces a text file as the output. The text template transformation engine controls the process, and the engine interacts with a text template transformation host and one or more text template directive processors to complete the process. For more information, see Architecture of the Text Template Transformation Process.

To create a custom directive processor, you create a class that inherits from either DirectiveProcessor or RequiresProvidesDirectiveProcessor.

The difference between these two is that DirectiveProcessor implements the minimum interface that is necessary to capture parameters from the user and to provide functionality to the generated transformation class. RequiresProvidesDirectiveProcessor defines and implements a design pattern called requires/provides. RequiresProvidesDirectiveProcessor provides richer facilities to capture parameters from the user and to provide functionality to the generated transformation class, with specific property names. The language user of the text template can also override the property names.

For example, a custom directive processor might accept a file name from the language user, open and read the file, and then store the text of the file in a variable that is named fileText. A custom requires/provides directive processor might accept a file name from the user and the name of the variable in which the user would like to store the text. This processor would open and read the file and then store the text of the file in a variable that has the name that the language user specified.

Before you call a custom directive processor from a text template in Visual Studio, you must enter the directive in the registry. If you use the command-line tool to transform text templates, you do not need to enter the processor in the registry. For more information, see Command-Line Tools for Text Templates.

For more information about adding the registry key, see Setting the Registry Key for Custom Directive Processors.

In This Section

• Setting the Registry Key for Custom Directive Processors
  Explains how to set the registry key for the custom directive processor.

• Walkthrough: Creating a Custom Directive Processor
  Walks you through the process of creating a custom directive processor that reads an XML file, adding the key to the registry, testing the directive processor, and formatting the output file as HTML.

Reference

DirectiveProcessor

RequiresProvidesDirectiveProcessor

Related Sections

• Advanced Tasks with Text Templates
  Contains topics about advanced text template tasks, such as creating custom host and directive processor components.

• Architecture of Text Templates
  Contains topics that discuss the architecture of the text template transformation process in detail.

• Generating Artifacts By Using Text Templates
  Describes the use of text templates to generate artifacts such as text reports, code, or HTML files.

• Directive Syntax (Domain-Specific Languages)
  Describes the syntax for using built-in directives.

• Domain-Specific Language Tools Glossary
  Defines key terms that are used in the Help for Domain-Specific Language Tools.