Features

Visual Studio project templates and item templates are reusable and customizable stubs that can simplify the development process. They provide pre-defined starting points for the project or the project items, thus removing the need to create new projects and items from scratch every time.

A Visual Studio template is represented by an icon, a name and a description in the New Project dialog or the Add New Item dialog. Behind the scene, each template is a compressed .zip file located in a special folder. Managing templates is as easy as managing files.

Visual Studio 2005 installs a number of project templates and item templates to your computer by default. When creating a new project, a developer will have several categories of projects to choose from, as shown in Figure 1. For example, the more common Windows projects include Windows Application and Class Library. These are called Project Templates. A project template contains the files and settings necessary to create a project, such as name and description for this project template, assembly references, default project contents, default project properties, and compiler options. In Figure 1, select the Windows Application template under the Windows project type to create a default C# Windows Form project.

Once the project is created, project items can be added through the Add New Item dialog, as shown in Figure 2. This dialog box contains available pre-defined project item templates, such as Class and Interface. Each of these represents an Item Template. An item template contains the files and settings necessary to create a project item. In Figure 2, select Windows Form to add a new Form class to the project.

Project templates and item templates allow for easy authoring of the project. Take a look at the Windows Form project we just created. The Windows Application project template sets up the required project properties and assembly references for a Windows Form project. The Windows Form item template creates an empty Form class and adds it to the project with the correct set of assembly references. Together, they free users from low level plumbing work and allow users to concentrate on the custom logic, thus accelerating the development process.

Project templates and item templates help distribute reusable code. For example, a company can standardize on a specific layout and style of the About Box with company logo and copyright information. The company's About Box item template could be distributed for reuse by teams within the company. It eliminates redundant coding and reduces possibility of visual inconsistencies between the company's products.

Project templates and item templates can be created and distributed by any developer. The rest of the article is dedicated to illustrating how to create project templates and item templates.

Export Template from Visual Studio
The Export Template wizard in Visual Studio 2005 allows one to create a template from an existing project. This is the easiest way to create basic templates. On the File menu, click Export Template to open the wizard. Figure 3 is a screenshot of the Export Template wizard.

The Export Template wizard supports both project templates and item templates. For project templates, it creates a template based on the existing project. For item templates, it allows the user to select desired items and assembly references to be included in the item template.

Upon finishing, the Export Template wizard generates a .zip file as the template. It contains the following files:

• The files to create when the template is invoked. This includes all source code files, embedded resources, the project file, etc.
• One .vstemplate file. This file contains the metadata that provides Visual Studio 2005 with the information it needs to display the template in the New Project or the Add New Item dialog boxes, and to create a project or item from the template.
• One icon file to be used in the display of the template within the New Project or Add New Item dialog.

The Export Template wizard copies the generated template file to <My Documents>\Visual Studio 2005\My Exported Templates\ folder. To register a template with Visual Studio 2005, the template .zip file needs to be copied to one of the following template folders:

<My Documents>\Visual Studio 2005\Templates\ProjectTemplates\ (for project templates)
<My Documents>\Visual Studio 2005\Templates\ItemTemplates\ (for item templates)

For a project template, the folder in which it resides determines where the template is displayed in the New Project dialog. If the project template file is under the ProjectTemplates\Visual C#\ folder, the template will be displayed under the Visual C# project type node in the New Project dialog. If it's under the ProjectTemplates\Visual C#\Windows\ folder, it will be displayed under the Windows project type node in the New Project dialog. The project template folder structure maps to the folder structure under <Visual Studio install folder>\Common7\IDE\ProjectTemplates\.

After copying the .zip file, the template will be acknowledged by Visual Studio 2005 and displayed the next time the New Project or Add New Item dialog is shown.

The .vstemplate File
Each template file must contain a single .vstemplate file. The name of the .vstemplate file is irrelevant, but it must exist at the root of the zip archive. The .vstemplate file stores the metadata for the template.

The .vstemplate file schema is the same for both the project templates and the item templates. Using the Export Template wizard on the Windows Form project we just created will generate a .vstemplate file similar to the one in Listing 1.

The first section TemplateData contains metadata used in the display of the template in the New Project dialog or the Add New Item dialog. Some common elements are:

• Name: The name of the template as it appears in the New Project dialog or the Add New Item dialog.
• Description: The description of the template as it appears in the New Project dialog or the Add New Item dialog.
• ProjectType: The category of the project template as it appears under the specified group in the New Project dialog.
• SortOrder: A value used to arrange the template, among other templates in the same category, as it appears in either the New Project dialog or the Add New Item dialog. Templates with smaller numbers appear first.
• DefaultName: The default name used for the project or item when it is created.
• Icon: Specifies the path of the image file that serves as the icon for the template.

  The second section TemplateContent contains the metadata for the content along with directives to the template engine that control how the template is instantiated each time. Some common elements are:
  

• Project: This is the source of the project file. It only applies to project templates.
• ProjectItem: Describes an item contained in the template to be copied to.
• References: Assembly references required by an item template.

  The ProjectItem element may contain attributes to affect the behavior of the project template. They are:
  

• ReplaceParameters: A Boolean attribute specifying whether the item has parameters that must be replaced when a project is created from the template.
• TargetFileName: Specifies the name of the item that is created from the template.
• OpenInEditor attribute: A Boolean value specifying whether this item should be opened in its respective editor in Visual Studio 2005 when a project is created from this template.
• OpenInWebBrowser attribute: A Boolean value specifying whether the item should be opened the Web browser when a project is created from the template.
• OpenInHelpBrowser attribute: A Boolean value specifying whether the item should be opened in the Help viewer when a project is created from the template.
• OpenOrder attribute: Specifies a numeric value that represents the order that items will be opened in their respective editors. Items with lower OpenOrder values are opened first.

For more information about the .vstemplate file schema, please refer to documentation in MSDN.

Parameter Replacement
A file in a project template or an item template can support parameter replacement. This is a very powerful feature. The parameter replacement mechanism allows placing parameters (tokens) inside the file and replacing them with dynamic information when the final file is generated.

When creating a template, the Export Template wizard replaces some of the important code with tokens. For example, an item template created from a Form class will have its namespace and class name replaced with parameter $rootnamespace$ and $safeitemname$. They are used as placeholders for the project's namespace and the item's name. When the template is invoked, these parameters will be replaced by the real project's namespace and the item name entered in the Add New Item dialog.

By default, Visual Studio 2005 supports a set of reserved template parameters:

• clrversion: Current version of the common language runtime (CLR).
• guid[1-10]: A randomly generated GUID. You can specify up to 10 unique GUIDs (for example, guid1).
• itemname: The name provided by the user in the Add New Item dialog box.
• machinename: The current computer name (for example, Computer01).
• projectname: The name provided by the user in the New Project dialog box.
• registeredorganization: The registry key value from HKLM\Software\Microsoft\Windows NT\CurrentVersion\RegisteredOrganization.
• rootnamespace: The root namespace of the current project. This parameter is used to replace the namespace in an item being added to a project.
• safeitemname: The name provided by the user in the Add New Item dialog box, with all unsafe characters and spaces removed.
• safeprojectname: The name provided by the user in the New Project dialog box, with all unsafe characters and spaces removed.
• time: The current time.
• userdomain: The current user domain.
• username: The current user name.
• year: The current year in the format YYYY.