Update to Text Templating syntax for May 2005 CTP
In April, I posted a summary of the syntax for the code generation engine supplied with the DSL Tools March CTP.
As we've now released our May CTP based on Visual Studio 2005 Beta 2, it seems it's time to update that post for our new text templating syntax.
Note that the file extensions for templates have all changed in the May 2005 CTP.
Templates consist of some directives followed by a mixture of literal blocks and control blocks. Literal blocks are just plain text in the template that you want to pass straight through to the output. Control blocks are things with some kind of <# #> marker around them.
The content of these blocks in your template contributes to a class which the templating system generates. This class derives from the abstract class Microsoft.VisualStudio.TextTemplating.TextTransformation and overrides the abstract method TransformText which, when executed, writes out the desired output of the transformation of the template. If you do nothing else in your template, this method will write out all of the text in literal blocks by simply writing out the raw text using a simple WriteLine()-style statement. The base class provides this WriteLine method (in various flavors) as well as Error and Warning methods that you can use in your custom template code.
Control blocks
You can add three types of control block in this release:
<# #> - Regular control block
Embeds some control code in the TransformText method.
Regular control blocks affect the literal blocks that they surround by means of the flow of control within them. This happens because the regular blocks' code is written verbatim into the TransformText method. So if you have a regular block that begins a for loop that loops five times, then have a literal block, then have another regular block that closes the for loop, you'll get the contents of the literal block written into the final output text five times. You'd typically use some expression blocks inside this loop to do something interesting with the loop variable. You can put anything in a regular block that you can put in the body of an overriden virtual method.
<#= #> - Expression control block
Embeds the value of a C# or VB.Net expression.
The expression will automatically have .ToString() appended to it (with the template's culture, if provided).
<#+ #> - Class features control block
Embeds control code at the TextTransformation-derived class scope.
This block allows you to add new methods, fields, properties, embedded classes etc. to the class derived from TextTransformation. You can then use these from regular and expression control blocks.
Trying to write all of your control code inside one method can be tiresome if you have a big model to traverse - especially if the model has a recursive structure like a tree in it. Class features blocks allow you to add further methods to the class to make this sort of thing easier and to structure your control code well. You can add anything that you'd find contained within a class in a class features block.
Directives
Directives have two purposes,
a) they provide instructions to the templating engine,
b) they inject code into the TextTemplating-derived class that performs the transformation process.
Their syntax is:
<#@ directiveName parameter="Value" #>
There is also more rich form of this which is commonly used:
<#@ directiveName parameter1="Argument1[='Value1'][;Argument2[=Value2]]" parameter2="Argument1[=Value1][;Argument2[='Value2']]" #>
This latter form enables more complex parameter lists to be passed to a directive processor while still conforming to the simpler syntax.
There are a number of directives built-in to the engine. Additionally, custom directives are created to tailor the text templating process for a specific application. A good example of this tailoring is that we provide custom directive processors to read model files into memory and make their content available for manipulation by code in control blocks within templates.
Standard Directives
<#@ template inherits="MyNamespace.MyBaseClass" language="C#" culture="en-US" debug="false" hostspecific="false" #>
Specifies transformation options for this template:
The inherits parameter specified the base class to use for the generated TextTransformation class. The default is Microsoft.VisualStudio.TextTemplating.TextTransformation. A custom base class "Microsoft.VisualStudio.TextTemplating.VSHost.ModelingTextTransformation" is provided with the DSL Tools that works together with custom directive processors to make it easy to read in and process model files. Custom base classes must themselves ultimately be derived from Microsoft.VisualStudio.TextTemplating.TextTransformation.
The language parameter specifies which programming language is used in code inside control blocks. The supported languages are "VB" and "C#", where "VB" denotes Visual Basic.Net.
The culture parameter specifies which .Net culture is used to format the values evaluated from from expression control blocks. The standard .Net "xx-XX" specifier must be used.
The debug parameter leaves the code generated dynamically for the transformation process on disk rather than working wholly in memory. This can aid in debugging complex template issues. This code can be found in the logged-in user's temporary directory (typically <drive>:\Documents and Settings\<username>\Local Settings\Temp).
The hostspecific parameter specifies whether the application hosting the Text Transformation engine should make a reference to itself available to template control code. This can be useful in circumstances where the code executing as part of the template is intended to work with only a single host and to make use of facilities provided by that host. Do not set this value to true if you wish your templates to execute in multiple hosting environments, for example, inside Visual Studio and from the command-line template processor. Setting this value to true will contribute a property called "Host" to the TextTransformation-derived class. DSL Tools users would not usually use this parameter, as they are using a set of hosts provided by the DSL Tools themselves.
<#@ output extension=".cs" #>
Specify the extension of the file that gets generated.
<#@ assembly name="System.Drawing.dll" #>
Reference the assembly in compilation of control blocks.
<#@ import namespace="System.Collections" #>
Import the namespace in compilation of control blocks. (i.e. a C# using statement)
For .dsldmt templates:
<#@ include file="FileToInclude.dsldmi" #>
Include the content of the file "FileToInclude.dsldmi" either from the same directory as the template containing the include directive, or from the TextTemplates directory under the DSL Tools install point.
<#@ model processor="DMDirectiveProcessor" requires="fileName='UtilitiesModel.dsldm'" provides="Model=Model" #>
This custom directive processor loads the given domain model into memory and provides a reference to its root object in the property "Model" on TextTransformation-derived class.
Modifying the provides clause to say "Model=OtherPropertyName" would instead provide a property called OtherPropertyName.
For .dslddt templates:
<#@ include file="FileToInclude.dslddi" #>
Include the content of the file "FileToInclude.dslddi" either from the same directory as the template containing the include directive, or from the TextTemplates directory under the DSL Tools install point.
<#@ definition processor="DDDirectiveProcessor" requires="fileName='..\\SimpleArchitectureChart.dsldd'" provides="Definition=Definition" #>
This custom directive processor loads the given designer definition into memory and provides a reference to its root object in the property "Definition" on the TextTransformation-derived class.
Modifying the provides clause to say "Definition=OtherPropertyName" would instead provide a property called OtherPropertyName.
Escaping
Occasionally, it is necessary to escape the syntax of the text templates (for example, to create a template that itself generates another template for later transformation). The syntax to accomplish this is as follows:
\<#
\#>
Also, it may be necessary to escape a quotation character within a directive. This can be achieved with the following syntax:
<#@ directive argument="BeforeQuote\"AfterQuote" #>
Binding to Visual Studio
There are several programmatic ways to access the Text Templating engine. However, inside Visual Studio, the current method of choice is to use the established CustomTool mechanism.
On any file that you want treated as a text template, select it in the Solution Explorer and in the Properties Grid, modify the Custom Tool entry to say "TextTemplatingFileGenerator". The output of the template will then be rendered as a dependent file underneath the template file.
Running templates in batch mode
A batch-mode command-line processor for templates is provided. The executable is called VsTextTransform.exe.
Comments
- Anonymous
June 20, 2005
Martin has just put up an article on Language Workbenches - IDEs for creating and using DSLs.
As you'd... - Anonymous
July 04, 2005
On Language Workbenches:
Martin Fowler’s original post x and additional readings x
Brad Appleton’s... - Anonymous
July 04, 2005
On Language Workbenches:
Martin Fowler’s original post &oplus; and additional readings &oplus;... - Anonymous
July 06, 2005
On Language Workbenches:
Martin Fowler’s original post ⊕ and additional readings ⊕
Brad Appleton’s... - Anonymous
June 02, 2006
A caching question: Using the standard templating engine (Microsoft.VisualStudio.TextTemplating.Engine), is there a way to cache the same template file between generations? Specifically, the engine.ProcessTemplate seems to recompile the template each time. Is there a way to cache it? It's taking us minutes to generate 200-300 templates all based on a single template file with different arguments being passed to it.
The code is as easy as: engine.ProcessTemplate(contentStr, new TemplateHost(".", templateArgs).
The T4 engine is fantastic, but becoming harder and harder to work with as we generate more and more. You seem to have lots of good info on this topic, thus my post.
Thanks! - Anonymous
July 14, 2006
The comment has been removed - Anonymous
September 22, 2008
I've been fielding questions about the syntax of our Text Templating technology (whose codename is "T4")