Directives and directive processors provide additional functionality to text templates. This functionality can be a simple as the ability to specify the extension of the output file or as complex as custom directive processors that read data from a database. A directive processor contains one or more directives. The same directive processor can process more than one directive. As an analogy, you can think of directive processors as classes, and you can think of directives as methods in those classes. You call directives directly from your text templates.
Directives fall into one of three types:
Directive Type
|
Description
|
Difficulty
|
Frequency of Use
|
See Also
|
|---|
Built-in
|
Built-in directives are provided by the text template transformation toolkit. By using built-in directives, you can specify common options such as the programming language of the text template and the extension of the output file. There are five built-in directives: assembly, import, template, output, and include. For more information, including the syntax to call a built-in directive, see Directive Syntax (Domain-Specific Languages).
|
Basic
|
Often
| Using Built-in Directives in Text Templates |
Generated
|
Generated directives are based on the domain-specific language that you create. If you call a generated directive, you can access models from the statements and expressions in text templates. For more information, see Generated Directives.
|
Intermediate
|
Often
| Accessing Models from Text Templates |
Custom
|
You can write custom directives to provide custom functionality to text templates. You can use a custom directive processor any time that you want to access external data. For more information, see Custom Directives.
|
Advanced
|
Rarely
| Creating Custom Text Template Directive Processors |
Directives work by adding code to the generated transformation class. You call directives from a text template, and the engine processes all of the directive calls when it creates the generated transformation class. After you call a directive successfully, the rest of the code that you write in your text template can rely on the functionality that the directive provides. For example, you can make the following call to the import directive in your template:
<#@ import namespace="System.Text" #>
If you make such a call, you can then use the StringBuilder class in the rest of your template code without qualifying it as System.Text.StringBuilder.
Generated Directives
When you use Domain-Specific Language Tools to create a domain model, the tools generate a directive processor for your domain model. By calling the generated directive processor from a text template, you can access the domain classes that underlie a model. You can then write code in the text template that creates reports or code based on the model.
For example, you can run the Minimal Language wizard, build and run the solution, create a text template, and add the following directive call to it:
<#@ examplemodel processor="DSLMinimalTestDirectiveProcessor" requires="fileName='Sample.min'" provides="ExampleModel=ExampleModel" #>
In this example, DSLMinimalTestDirectiveProcessor is the generated directive processor, and ExampleModel is the directive. After you call the directive, you can access the model in the text template code. For example, you can specify the following:
Model: <#=this.ExampleModel.Name#>
For more information, see Accessing Models from Text Templates.
Custom Directives
You can write custom directive processors to provide custom functionality to your text templates. You can use a custom directive processor any time that you want to access external data or resources from a text template.
Different text templates can share the functionality that a single directive processor provides, so directive processors provide a way to factor code for reuse. The built-in include directive is similar, because you can use it to factor out code and share it among different text templates. The difference is that any functionality that the include directive provides is fixed and does not accept parameters. If you want to provide common functionality to a text template and allow the template to pass parameters, you must create a custom directive processor.
Some examples of custom directive processors could be:
A directive processor to return data from a database that accepts a user name and password as parameters.
A directive processor to open and read a file that accepts the name of the file as a parameter.
For more information, see Walkthrough: Creating a Custom Directive Processor.