Oleg Sych

Here is how MSDN documentation defines the assembly directive.

The assembly directive identifies an assembly to be referenced so that you can use types within that assembly from code in the text template. Using the assembly directive is equivalent to using the Add Reference feature in Visual Studio.

This directive does not affect the source code of the compiled template. Instead it affects compiler options T4 uses to compile GeneratedTextTransformation into a .NET assembly. Here is an example of a T4 template and C# compiler T4 uses to compile it.

Template

<#@ template language="C#" debug="True" #>
<#@ assembly name="System.Data" #>
<#@ assembly name="System.Xml" #>
<#@ import namespace="System.Data" #>
<#
    DataSet dataSet = new DataSet();
#>

Compiler Options

/t:library /utf8output /D:DEBUG /debug+ /optimize- /w:4
/R:"...\System.dll"
/R:"...\System.Data.dll"
/R:"...\System.Xml.dll"
/R:"...\Microsoft.VisualStudio.TextTemplating.VSHost.dll"
/R:"...\Microsoft.VisualStudio.TextTemplating.dll"
/out:"...\qcckmauz.dll"
"...\qcckmauz.0.cs"

As you can see, a template with two assembly directives is compiled with references to the assemblies they specify. This allows you to use code from any .NET assemblies in your template.

How T4 resolves assembly names

Name property of the assembly directive can contain either a rooted file path or an assembly name.

Rooted File Path

If the name property contains a rooted file path (path that includes drive letter, such as "C:\MyAssembly.dll"), T4 will go to the file directly. Here is an example of a template that uses this option and command line options T4 generates to compile this template.

Template 

<#@ template language="C#" #>
<#@ assembly name="C:\ClassLibrary1\bin\Debug\ClassLibrary1.dll" #>

Compiler Options

/t:library /utf8output /D:DEBUG /debug+ /optimize- /w:4
/R:"C:\ClassLibrary1\bin\Debug\ClassLibrary1.dll"
/R:"C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727\System.dll"
/R:"C:\WINDOWS\assembly\...\Microsoft.VisualStudio.TextTemplating.VSHost.dll"
/R:"C:\WINDOWS\assembly\...\Microsoft.VisualStudio.TextTemplating.dll"
/out:"C:\Documents and Settings\...\Local Settings\Temp\2jniyhqf.dll"
"C:\Documents and Settings\...\Local Settings\Temp\2jniyhqf.0.cs"

Main disadvantage of this approach is that it requires using absolute file paths, making it difficult to use in team environment where different developers have different folder structures on their workstations.

Global Assembly Cache

If the name property does not contain a rooted file path, T4 will first try to find the assembly in the GAC. Assembly name in this case can be a strong name with assembly version, culture and public key token information. In the example above, T4 located System.Data assembly in the global assembly cache.

Project Properties

If the assembly cannot be found in the global assembly cache, T4 will try to find it using properties of the project to which the T4 template itself belongs. It will first try to find the assembly among assemblies referenced by the project. If assembly still cannot be found, it will then search in the folders specified in project Reference Paths.

Here’s a modified version of the template, which can be used in either one of these two projects:

<#@ template language="C#" debug="True" #>
<#@ assembly name="ClassLibrary1.dll" #>

T4 generates the same command line options to compile this template as the one in previous example, which relies on rooted file path. Compared to rooted file paths, using project properties allows to avoid hard-coding absolute file paths to the assemblies because project references use relative paths by default. The main drawback of this approach is that it will work only when template is transformed by T4 custom tool in Visual Studio. It will not work when template is transformed by the TextTransform.exe (T4 command line host) which doesn’t know if T4 template belongs to a project.

About T4

T4 (Text Template Transformation Toolkit) is a template-based code generation engine. It is available in Visual Studio 2008 and as a download in DSL and GAT toolkits for Visual Studio 2005. T4 engine allows you to use ASP.NET-like template syntax to generate C#, T-SQL, XML or any other text files.

Ready for more? Read about <#@ include #> directive or go back to the overview.