Code Generation and T4 Text

Templates

1. What is T4?
2. Design Time T4 Text Templates
3. Run Time T4 Text Templates
4. Writing a T4 Text Template
5. Debugging a T4 Text Template
6. Customizing T4 Text Transformation
7. Code Generation in a Build Process
8. Security of Text Templates
What is T4?
T4 is an abbreviation for Text
Template Transformation Toolkit.
T4 text template is a mixture of text
blocks and control logic that can
generate a text file.
There are two kinds of T4 text
templates:
Run time T4 text templates.
Design time T4 text templates.
Design Time T4 Text Templates
Design time T4 text templates are
executed in Visual Studio to define
part of the source code and other
resources of your application.
Custom Tool property of the file
is TextTemplatingFileGenerator.
Run Time T4 Text Templates
Run time T4 text
templates (preprocessed templates)
are executed in your application to
produce text strings, typically as part
of its output.
Custom Tool property is set
to TextTemplatingFilePreprocessor.
Demo
Writing a T4 Text Template
Text templates are composed of the
following parts:
Directives - elements that control how
the template is processed.
Text blocks - content that is copied
directly to the output.
Control blocks - program code that
inserts variable values into the text, and
controls conditional or repeated parts of
the text.
Text Template Directives
T4 Template Directive
T4 Parameter Directive
T4 Output Directive
T4 Assembly Directive
T4 Import Directive
T4 Include Directive
T4 CleanUpBehavior Directive
T4 Template Directive
<#@ template [language="VB"]
[compilerOptions="options"]
[culture="code"] [debug="true"]
[hostspecific="true"]
[inherits="templateBaseClass"]
[visibility="internal"]
[linePragmas="false"] #>
T4 Parameter Directive
<#@ parameter
type="Full.TypeName"
name="ParameterName" #>
T4 Output Directive
<#@ output
extension=".fileNameExtension"
[encoding="encoding"] #>
T4 Assembly Directive
<#@ assembly name="[assembly
strong name|assembly file name]"
#>
T4 Import Directive
<#@ import
namespace="namespace" #>
T4 Include Directive
<#@ include file="filePath"
[once="true"] #>
T4 CleanUpBehavior Directive
<#@ CleanupBehavior
processor="T4VSHost"
CleanupAfterProcessingtemplate="
true" #>
Demo
Text Template Control Blocks
<# Standard control blocks #> can
contain statements.
<#= Expression control blocks #> can
contain expressions.
<#+ Class feature control blocks
#> can contain methods, fields and
properties.
Demo
Text Template Utility Methods
There are several methods that are
always available to you when you write
code in a Visual Studio text template.
Demo
Debugging a T4 Text Template
Set breakpoints in text templates.
To debug a design-time text template,
save the text template file, and then
choose Debug T4 Template on the
shortcut menu of the file in Solution
Explorer.
To debug a run-time text template,
simply debug the application to which
it belongs.
Demo
Customizing T4 Text
Transformation

Understanding The Text Template

Transformation Process
Creating Custom T4 Text Template
Directive Processors
Processing Text Templates by using a
Custom Host
The Text Template Transformation
Process

The engine controls the process, it

interacts with the host and the directive
processor to produce the output file.
The host provides any interaction with the
environment, such as locating files and
assemblies.
The directive processor adds
functionality, such as reading data from an
XML file or a database.
The Text Template Transformation
Process (con)

The engine creates a temporary class

(generated transformation class). This
class contains the code that is
generated by the directives and
control blocks.
The engine compiles and executes
the generated transformation class to
produce the output file.
Creating Custom T4 Text Template
Directive Processors

Inherit
from either DirectiveProcessor or
RequiresProvidesDirectiveProcessor.
Must implement these methods:
bool IsDirectiveSupported(string directiveName)
void ProcessDirective (string directiveName,
IDictionary<string, string> arguments)
Afterall calls to ProcessDirective() the templating
engine will call these methods:
string[] GetReferencesForProcessingRun()
string[] GetImportsForProcessingRun()
string GetClassCodeForProcessingRun()
Demo
Processing Text Templates by using a
Custom Host

There are two ways to call the text

transformation engine:
From a Visual Studio extension.
From a standalone application.
Demo
Code Generation in a Build
Process

Visual Studio doesnt transform the

file automatically.
Transforming templates as part of the
build makes sure that everythings up
to date.
Security of Text Templates

Text templates are vulnerable to

arbitrary code insertions.
If the mechanism that the host uses to
find a directive processor is not
secure, a malicious directive
processor could be run.