Oleg Sych

Visual Studio Templates is an extensible system of project and project item templates included in Visual Studio 2005 and 2008. A large number of predefined templates is installed out of the box. Screenshoot on the right shows the list of C# project item templates installed with Visual Studio 2008 Professional. You can quickly create new templates for individual project items and entire projects using Export Template wizard. Matt Milner’s gives a good overview of Visual Studio Templates in this article published by MSDN magazine in 2006. Dylan Miles published a video on MSDN that walks you through the process of creating project and item templates using Export Template wizard.

Template Syntax

Visual Studio Templates provide a simple code generation mechanism in the form of template parameters. Here is an extract from the built-in Class template:

using System;
using System.Collections.Generic;
$if$ ($targetframeworkversion$ == 3.5)using System.Linq;
$endif$using System.Text;

namespace $rootnamespace$
{
    class $safeitemrootname$
    {
    }
}

When generating actual file that will be added to the project, Visual Studio replaces $rootnamespace$ parameter with the default project namespace combined with the project folder to which new class is being added. $safeitemname$ template parameter is replaced with a valid programmatic identifier generated from the original file name by removing extension and replacing spaces with underscores. For example, if you add a new class called "1 Class.cs" to a folder called "Folder 1" in a C# project, Visual Studio will generate the following code.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;

namespace ConsoleApplication4.Folder_1
{
    class _1_Class
    {
    }
}

Template Structure

Built-in project and project item templates are installed to <Program Files>\Microsoft Visual Studio 9.0\Common7\IDE\ProjectTemplates and C:\Program Files\Microsoft Visual Studio 9.0\Common7\IDE\ItemTemplates folders. Visual Studio looks for custom templates created by developers in the <user profile>\My Documents\Visual Studio <version>\Templates folder. A typical Visual Studio Template is a ZIP archive that contains a .vstemplate file, an optional icon file and one or more template files.

VSTEMPLATE file

This file provides information to Visual Studio on how to display the template in the Add New Item dialog and what to do when user adds this item to the project. For example:

<VSTemplate Version="2.0.0" Type="Item"
  xmlns="http://schemas.microsoft.com/developer/vstemplate/2005">
  <TemplateData>
    <DefaultName>Class.tt</DefaultName>
    <Name>Class Template</Name>
    <Description>A text template for generating a C# class.</Description>
    <ProjectType>CSharp</ProjectType>
    <Icon>TextTemplate.ico</Icon>
  </TemplateData>
  <TemplateContent>
    <References />
    <ProjectItem ReplaceParameters="true" TargetFileName="$fileinputname$.tt">
      Class.tt
    </ProjectItem>
  </TemplateContent>
</VSTemplate>

Name, Description and Icon elements define how this project item will appear in the Add New Item dialog. DefaultName element defines a file name Visual Studio will suggest when user selects this template in the Add New Item dialog. ProjectType element determines for which types of projects this template will be available. Template in this example will be available only in C# projects.

References element allows to define additional references (if any) that Visual Studio will add to the project when this template is selected.

ProjectItem element defines a file that will be added to the current project when user selects this template. Notice that ReplaceParameters parameter is set to true. This enables parameter substitution in the template file. You can have more than one ProjectItem element if you need to add multiple files. For example, the built-in Form template (Windows Forms), includes two ProjectItem elements (Form.cs and Form.Designer.cs).

Template File

Template file is, well, a template of the actual file that will be added to the project when user selects this template in Add New Item dialog. The following .tt file is a Visual Studio Template of an actual T4 .tt template that will be added to the project.

<#
// $itemname$.tt
// Copyright © $year$ $registeredorganization$
//
// For more information and examples of text templates visit
// http://www.olegsych.com/2007/12/text-template-transformation-toolkit
#>
<#@ template language="C#" debug="True" hostspecific="True" #>
<#@ import namespace="System.Diagnostics" #>
<#@ import namespace="System.IO" #>
// <autogenerated>
//   This file was generated using <#= Path.GetFileName(Host.TemplateFile) #>.
//   Any changes made manually will be lost next time the file is regenerated.
// </autogenerated>
<#
    // To debug code generation, uncomment the following line
    // Debugger.Break();

    // TODO: Place template initialization code here.
#>
using System;

namespace $rootnamespace$
{
    public class $safeitemname$
    {
<#
    // TODO: Place template generation code here.
#>
    }
}
<#+
    // TODO: Place template class features here.
#>

This file uses $rootnamespace$, $safeitemname$ and other template parameters to customize the actual file that will be added to the project. Visual Studio will replace parameters with actual values when adding this file to the project.

Icon File

Visual Studio uses icon file from the ZIP archive when displaying the template in the Add New Item dialog. Default file used by Visual Studio Export Template wizard is different from the icon used by .tt files. Visual Studio Template in this example uses TextTemplate.ico which was installed by DSL toolkit in C:\Program Files\Common Files\Microsoft Shared\TextTemplating\1.2 folder.

Usage

Here are the steps you need to do to install and use use the T4 Class Template described in this article on your computer.

• Download T4 class template using the link below.
• Copy downloaded ZIP file (as is, don’t extract) to the following directory on your computer.
  
  <your profile>\My Documents\Visual Studio <version>\Templates\ItemTemplates\Visual C#

  where

  <your profile> is the folder where your profile is stored (C:\Documents and Settings\account on Windows XP or C:\Users\account on Windows Vista)

  <version> is the version of Visual Studio you are using (2005 or 2008).

• Create new or open existing C# project in Visual Studio
• Select Project->Add New Item in Visual Studio main menu. You should see the template in the My Templates section of the Add New Item dialog.
• Type in desired name for the new template and click Add.
• Visual Studio will add a new .tt file with the specified name to your current project. Template text will be similar to this.

<#
// Class1.tt
// Copyright © 2008 Catapult International
//
// For more information and examples of text templates visit
// http://www.olegsych.com/2007/12/text-template-transformation-toolkit
#>
<#@ template language="C#" debug="True" hostspecific="True" #>
<#@ import namespace="System.Diagnostics" #>
<#@ import namespace="System.IO" #>
// <autogenerated>
//   This file was generated using <#= Path.GetFileName(Host.TemplateFile) #>.
//   Any changes made manually will be lost next time the file is regenerated.
// </autogenerated>
<#
    // To debug code generation, uncomment the following line
    // Debugger.Break();

    // TODO: Place template initialization code here.
#>
using System;

namespace ConsoleApplication4
{
    public class Class1
    {
<#
    // TODO: Place template generation code here.
#>
    }
}
<#+
    // TODO: Place template class features here.
#>

Conclusion

Visual Studio Templates complement T4 Text Templates by allowing you to quickly generate simple boilerplate code for repetitive tasks, such as creating View, Controller and Presenter classes used in MVP and MVC patterns. T4 text templates are appropriate for more complex code generation, which requires synchronization of multiple source code files, such as generating CRUD stored procedures for a database table. Visual Studio Templates are easier to create than T4 templates and more appropriate when overhead of T4 complexity is too big compared for code that needs to be generated. Unlike T4, Visual Studio Templates can generate multiple files from a single template item.

Download

ClassTemplate.zip