How to: Call a Generated Directive

When you create a text template, you can call one or more of the five built-in directives: assembly, import, template, output, and include. For example, you call the output directive using the following syntax:

<#@ output extension=".txt" #>

In addition to calling built-in directives, you can also call generated directives, which make elements of your models available for use in text templates. To call a generated directive processor from a text template, you add the name of the directive and then specify parameters for the name of the directive processor, the file name of the model that you want to access, and the name that you want to use to refer to your model in the text template code.

For more information, see Accessing Models from Text Templates.

To call a generated directive processor

1. In your text template, add a directive statement, and specify the name of the directive. For example, add the following:

   <#@ ModelRoot #>
   

   The name of the directive matches the name of the root domain class in your domain model. By default, the name of the root domain class depends on the solution template on which you based your language. The following table shows the default directive names:

   Solution Template	Directive Name
   Activity Diagrams	ActivityGraph
   Class Diagrams	ModelRoot
   Minimal Language	ExampleModel
   Use Case Diagrams	UseCaseModel

   For example, if you have created a domain-specific language from the Activity Diagrams solution template and you did not rename the root domain class, your directive statement will look like the following instead:

   <#@ ActivityGraph #>
   

2. Add a processor parameter to your directive statement, and specify the name of the directive processor. For example, add the following:

   <#@ ModelRoot processor="XYZDirectiveProcessor" #>
   

   Note

   The name of the directive processor is the name of your language with DirectiveProcessor appended to it. You specified the name of your language in the Domain-Specific Language Designer Wizard. You can also find the name of your language in your domain-specific language solution. In the file Designer\Designer.dsldd, the name attribute of the <designerDefinition> tag (at the top of the file) is the name of your language.

3. Add a requires parameter to your directive statement, and specify the file name of the model that you want to access from the text template. For example, add the following:

   <#@ ModelRoot processor="XYZDirectiveProcessor" requires="fileName='<YourFileName>'" #>
   

   Replace <YourFileName> with the file name of the model file that you want to access.

   You can determine when the model file should be validated. For example, add the following to the requires parameter:

   <#@ ModelRoot processor="XYZDirectiveProcessor" requires="fileName='<YourFileName>';validation='open|menu|close'" #>
   

   By default, if the validation parameter is not listed, no validation occurs for the model file. To learn more about the validation parameter and the values you can assign to it, see Validation Overview for Domain-Specific Languages.

4. Add a provides parameter to your directive statement, and specify the name by which you want to refer to the model in the text template. For example, add the following:

   <#@ ModelRoot processor="XYZDirectiveProcessor" requires="fileName='<YourFileName>';validation='open|menu|close'" provides="ModelRoot=ModelRoot" #>
   

   The name of the provides parameter matches the name of the directive.

   By default, the value of this parameter is the same as its name, but you can change the value to anything you want. For example, you could write the following:

   <#@ ModelRoot processor="XYZDirectiveProcessor" requires="fileName='<YourFileName>';validation='open|menu|close'" provides="ModelRoot=LibraryModel" #>
   

   The most common reason to change the value of the provides parameter is if you are accessing more than one model from the same text template. In that case, you must specify different values for the provides parameters in each directive statement. For example, you could write the following:

   <#@ ExampleModel processor=" XYZDirectiveProcessor " requires="fileName='<YourFileName>';validation='open|menu|close'" provides="ExampleModel=SchoolModel" #>
   <#@ ExampleModel processor=" XYZDirectiveProcessor " requires="fileName='<YourFileName>';validation='open|menu|close'" provides="ExampleModel=WorkModel" #>
   

   Note

   To debug text templates, you must set the debug parameter of the template directive. For more information, see Walkthrough: Debugging a Text Template.

Security

For more information, see Security of Text Templates.

See Also

Tasks

How to: Call a Custom Directive

Concepts

Accessing Models from Text Templates

Architecture of the Text Template Transformation Process

Change History