Accessing Models from Text Templates

By using text templates, you can create reports, code, or other artifacts from models. For more information, see Generating Artifacts By Using Text Templates. Before you can access a model from the statements and expressions in a text template, you must first call a generated directive processor.

Generated Directive Processors

When you use Domain-Specific Language Tools to create a domain model, the code templates generate a directive processor for your domain model. They also define a directive that can be used to invoke the directive processor.

You can find the code for the generated directive processor in the following location.

<YourSolutionName>\Dsl\GeneratedCode\DirectiveProcessor.cs

The name of the generated directive processor depends on the name of your domain-specific language.

Calling Generated Directive Processors

To access a model from your text template code, you must invoke the generated directive processor using the generated directive. Invoking the generated directive processor makes the classes in your model available as properties to the text template code.

For example, the following directive would be appropriate for a DSL named ActivityGraph that uses the file extension .act:

<#@ ActivityGraph processor="ActivityGraphDirectiveProcessor" requires="fileName='SampleModel.act'" provides="ActivityGraph=ActivityGraph" #>

When you press F5 or CTRL+F5 to run the DSL in a debugging project, you will usually find that the example text template files in the debugging project contain an example of your language directive. However, the directive name will be incorrect if you have changed the language name since you created the solution.

The Requires and Provides Parameters

When you call a generated directive processor, you specify values for the requires parameter and the provides parameter.

In the requires parameter, you specify the name of the file that contains the model that you want to access in your text template. If you want to access more than one model from the same text template, you must call the generated directive processor again and specify the file name of the second model. For more information, see Accessing Multiple Models from a Text Template later in this topic.

In the provides parameter, you specify the name that you want to use to access your model. By default, you specify the name of the generated directive as the value for the provides parameter, for example,

<#@ ExampleModel processor="<YourLanguageName>DirectiveProcessor" requires="fileName='Sample.mmm'" provides="ExampleModel=ExampleModel" #>

If you do not want to use the default name, you can specify your own value for the provides parameter, for example,

<#@ ExampleModel processor="<YourLanguageName>DirectiveProcessor" requires="fileName='Sample.mmm'" provides="ExampleModel=MyLibraryModel" #>

You cannot use the default provides parameter value more than once. If you want to access more than one model from the same text template, you must specify a different value for all the provides parameters after the first directive call. For more information, see Accessing Multiple Models from a Text Template later in this topic.

Accessing a Model from a Text Template

After you have called the generated directive processor, you can access the model in your text template code. You refer to your model using the name that you specified in the provides parameter of your directive call. The following example shows text template code that accesses a model. In this example, the default name was specified in the provides parameter. Notice that this always has a property that has the same name and type as the the root domain class of your DSL.

<#
foreach (ExampleClass box in this.ExampleModel.Elements)
...
#>

<#
For Each box As ExampleClass In Me.ExampleModel.Elements
...
#>

Accessing Multiple Models from a Text Template

If you want to access more than one model from the same text template, you must call the generated directive processor once for each model that you want to access. You must specify the file name of each model in the requires parameters. You must specify the names that you want to use to access your models in the provides parameters. You must specify different values for the provides parameters in each of the directive calls. You cannot use the default values for each of the directive calls.

For example, assume you have three model files called Library.xyz, School.xyz, and Work.xyz. To access them from the same text template, you must write three directive calls that resemble the following ones.

<#@ ExampleModel processor="<YourLanguageName>DirectiveProcessor" requires="fileName='Library.xyz'" provides="ExampleModel=LibraryModel" #>
<#@ ExampleModel processor="<YourLanguageName>DirectiveProcessor" requires="fileName='School.xyz'" provides="ExampleModel=SchoolModel" #>
<#@ ExampleModel processor="<YourLanguageName>DirectiveProcessor" requires="fileName='Work.xyz'" provides="ExampleModel=WorkModel" #>

To access the models in your text template, you can now write code that resembles the following example.

<#
foreach (ExampleClass box in this.LibraryModel.Elements)
...
foreach (ExampleClass box in this.SchoolModel.Elements)
...
foreach (ExampleClass box in this.WorkModel.Elements)
...
#>

<#
For Each box As ExampleClass In Me.LibraryModel.Elements
...
For Each box As ExampleClass In Me.SchoolModel.Elements
...
For Each box As ExampleClass In Me.WorkModel.Elements
...
#>

Debugging

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 Generated Directive

Walkthrough: Creating and Running Text Templates

Other Resources

Architecture of Text Templates

Change History