Walkthrough: Using an Assembly in a Text Template

Article
11/16/2012

You can use text templates to generate code, text or HTML artifacts. For more information, see Generating Artifacts By Using Text Templates. By using the assembly directive in a text template, you can reference an assembly and then use the types and members from that assembly in your text template code. For example, in this walkthrough, you use an assembly that accepts a person's birth date in string format, and then returns that person's age by using an integer value.

This walkthrough illustrates the following tasks:

How to create a basic assembly.
How to create a text template.
How to use the assembly in the text template.

Prerequisites

To complete this walkthrough, you must have:

Visual Studio 2008.

Note

For a list of the Visual Studio 2008 editions that Domain-Specific Language Tools supports, see Supported Visual Studio Editions for Domain-Specific Language Tools.
Visual Studio 2008 SDK.

Creating a Basic Assembly

First you create a basic assembly to use in your text template.

Note

You create this assembly for testing only. You can use the assembly directive to reference any existing assembly.

The assembly has one class, which is named CustomFunctions, and one method, which is named GetAge. GetAge accepts a person's birth date in string form and returns the person's age.

To create a simple assembly

Create a new Visual Basic or C# class library project named CustomAssembly.

The system creates a class library project.

Replace the code in Class1 with the following code.

using System;

namespace CustomAssembly
{
    public static class CustomFunctions
    {
        public static int GetAge(string birthDate)
        {
            DateTime birth;

            try
            {
                birth = DateTime.Parse(birthDate);
            }
            catch (Exception ex)
            {
                throw new ApplicationException("Unable to read birth date.", ex);
            }

            if (DateTime.Today.Month < birth.Month)  //it is before your birthday
            {
                return DateTime.Today.Year - birth.Year - 1;
            }
            else if (DateTime.Today.Month > birth.Month)  //it is after your birthday
            {
                return DateTime.Today.Year - birth.Year;
            }
            else // DateTime.Today.Month == birth.Month  //we don't know yet
            {
                if (DateTime.Today.Day < birth.Day)  //it is before your birthday
                {
                    return DateTime.Today.Year - birth.Year - 1;
                }
                else //it is your birthday, or it is after your birthday
                {
                    return DateTime.Today.Year - birth.Year;
                }
            }
        }
    }
}

Imports System

Public Class CustomFunctions

    Public Shared Function GetAge(ByVal birthDate As String) As Integer

        Dim birth As DateTime

        Try
            birth = DateTime.Parse(birthDate)

        Catch ex As Exception

            Throw New ApplicationException("Unable to read birth date.", ex)
        End Try

        If (DateTime.Today.Month < birth.Month) Then  'it is before your birthday

            Return DateTime.Today.Year - birth.Year - 1

        ElseIf (DateTime.Today.Month > birth.Month) Then  'it is after your birthday

            Return DateTime.Today.Year - birth.Year

        Else ' DateTime.Today.Month == birth.Month  'we don't know yet

            If (DateTime.Today.Day < birth.Day) Then  'it is before your birthday

                Return DateTime.Today.Year - birth.Year - 1

            Else 'it is your birthday, or it is after your birthday

                Return DateTime.Today.Year - birth.Year
            End If
        End If
    End Function
End Class

Build and save the project.

Creating a Text Template

Next, you create a text template that uses the assembly.

To create a text template

Create a new Visual Basic or C# class library project named TemplateTest.

The system creates a class library project.
Add a text file named AssemblyTest.tt to the project.
Make sure that the Custom Tool property is set to TextTemplatingFileGenerator.
On the File menu, click Save All.

Using the Assembly in the Text Template

Finally, you use the types and methods from the assembly in your text template.

To use the assembly in the text template

Add the following directives to the top of AssemblyTest.tt to reference the assembly that you just created.

Note

The language of the text template does not have to match the language of the assembly.
```
<#@ assembly name="<YOUR PATH>\CustomAssembly\CustomAssembly\bin\Debug\CustomAssembly.dll" #>
<#@ import namespace="CustomAssembly" #>
<#@ output extension="txt" #>
```
```
<#@ assembly name="<YOUR PATH>\CustomAssembly\CustomAssembly\bin\Debug\CustomAssembly.dll" #>
<#@ import namespace="CustomAssembly" #>
<#@ template language="vb" #>
<#@ output extension="txt" #>
```
Note

In addition to the assembly directive, you also used the import directive to import a namespace from your assembly. These two directives are often used in conjunction.
In the code, replace <YOUR PATH> with the path of your assembly.

Note

If your assembly is installed in the global assembly cache, you can just specify the name of the assembly.

Add the following text block and statement to AssemblyTest.tt.

This code calls the GetAge function in the referenced assembly.

Welcome Ben Smith.
<#
    int age = CustomFunctions.GetAge("10/9/1940");
#>

Welcome Ben Smith.
<#
    Dim age as Integer = CustomFunctions.GetAge("10/9/1940")
#>

Add the following text block and expression to AssemblyTest.tt.

This code displays the result of calling the GetAge function.
```
Your current age is:
<#= age #>
```
```
Your current age is:
<#= age #>
```
In Solution Explorer, right-click AssemblyTest.tt, and then click Run Custom Tool.
In Solution Explorer, expand AssemblyTest.tt, and then double-click AssemblyTest.txt to open it in the editor.

The generated text output appears and resembles the following example.

Welcome Ben Smith.

Your current age is:

65

Security

For more information, see Security of Text Templates.

Next Steps

If you have problems with your code, you might want to try some debugging. To debug text templates, you must set the debug parameter of the template directive. For more information, see Walkthrough: Debugging a Text Template.

Change History

Date	History	Reason
July 2008	Rewrote and refactored project.	Content bug fix.

Walkthrough: Using an Assembly in a Text Template

Prerequisites

Creating a Basic Assembly

To create a simple assembly

Creating a Text Template

To create a text template

Using the Assembly in the Text Template

To use the assembly in the text template

Security

Next Steps

See Also

Tasks

Concepts

Other Resources

Change History

Additional resources