Create Your Own Project Item Templates in VS 2005

Visual Studio supports extensibility in a couple of ways. One way is to implement the IExtensibility2 interface; another is to implement the IDTWizard interface. An existing IDTWizard is contained in the VsWizard.dll. This wizard supports project items and project templates, permitting you to create a new project (like a console application). You also can use the VsWizard.dll wizard to implement your own templates.

In prior versions of VS.NET, you had to define a template file, modify some common script files (common.js and default.js), add some line items to a file named template.inf, create a wizard launch (.vsz) file, and create a VSDir file that indicated where the template was located, what it was called, and how to show it in the Add New Items dialog (or related dialogs). Visual Studio 2005 builds on the flexibility of XML, condensing this process and making it significantly quicker and easier.

This article demonstrates how to create your own templates in VS 2005. Specifically, it shows you how to create a typed collection project item template.

Create a Template Metadata File

Because templates are still based on VsWizard.dll, the XML metadata file needs some of the same values that were added to the older template-style elements. Fortunately, they are all contained in one file with a .vstemplate extension and described as XML. All you need to create a project item template is a .vstemplate file and a code file with optional replaceable parameters.

Listing 1 contains the .vstemplate for your typed collection. A brief description of significant elements follows the listing.

Listing 1: A project item template's .vstemplate file.

<VSTemplate Version="1.1.0" Type="Item">
   <TemplateData>
      <Name>
         <String>Typed Collection</String>
      </Name>
      <Description>
         <String>A strongly typed collection</String>
      </Description>
      <Icon>
         <Package GUID="{164B10B9-B200-11D0-8C61-00A0C91E29D5}"
                  ID="4556"/>
      </Icon>
      <ProjectType>
         <Languages>
            <Language>VisualBasic</Language>
         </Languages>
      </ProjectType>
      <SortOrder>20</SortOrder>
      <DefaultName>Collection.vb</DefaultName>
   </TemplateData>
   <TemplateContent>
      <ProjectItem>
         <SourceFile>Class1.vb</SourceFile>
         <ReplaceParameters>true</ReplaceParameters>
      </ProjectItem>
   </TemplateContent>
</VSTemplate>

The template file is named TypedCollectionTemplate.vstemplate. The elements are dictated by the wizard, which didn't use elements such as tags for assembly references but did use the following elements:

• VSTemplate indicates that the contents are for a template.
• The TemplateData tag replaces the elements you used to place in the VSDir file, including a name, description, and language. (The icon used is an existing icon defined for a pre-installed VS 2005 template. You can add an icon literal path or a resource identifier for a known icon.)
• The TemplateContent element indicates the element type—in this example, a project item—and the name of the source file that contains the template code.
• The ReplaceParameters tag indicates that the associated source file contains pre-defined replaceable parameters.

Jason Kemp published an article that is a good source for some additional information. His article includes examples of assembly references, GUIDs for existing elements like icons, and an interesting example of a NUnit template. For more information on typed collections, see my previous article, and for more on old-style templates see this one.

Create a Codefile

The code file is straightforward. A typed collection is a class that inherits from System.Collections.CollectionBase (or System.Collections.ReadOnlyCollectionBase for a read-only collection) and contains an Add method and an indexer. The indexer returns the collected type and permits you to treat the typed collection like an array of the collected type. Listing 2 contains the implementation of the template file.

Listing 2: An Implementation of a Template Typed Collection

Imports System
Imports System.Collections

Public Class $safeitemrootname$Collection
   Inherits CollectionBase

   Default Public Property Item(ByVal index As Integer) _
           As $safeitemrootname$
      Get
         return CType(List(index), $safeitemrootname$)
      End Get
      Set(ByVal value As $safeitemrootname$)
         List(index) = value
      End Set
   End Property

   Public Function Add(value as $safeitemrootname$) As Integer
      Return List.Add(value)
   End Function

End Class

The token $safeitemrootname$ represents a known replaceable parameter. The wizard will replace this token with the name you enter in the Add New Item dialog. I suffixed the class name with the Collection word, which will distinguish the class name from the type returned. To ensure that the return type reflects the type maintained by the collection, use the name of the collected type in the Add New Item dialog or modify this bit of code after the template is created.

One current drawback to templates is the lack of documentation of known tokens. This is an oversight that I hope is corrected before Whidbey ships.

Use the Project Item Template

To use the template, add the .vstemplate file and the code file to a zip file. (Windows XP supports zip files, or you can use WinZip). Place the zipped file in \My Documents\Visual Studio\ItemTemplates\Visual Basic. Restart Visual Studio 2005 and you will see a section in the Add New Item dialog under My Templates name Typed Collection (see Figure 1). Select this item to add a typed collection to any project.

Click here for a larger image.

Figure 1: The Typed Collection Project Item Template in Visual Studio 2005

A good technique is to build your template code and test it first. Once you remove any syntax errors or bugs, replace the literal values with template tokens and complete the process of moving the template files to the My Documents folder.

After you have created the template, use it to add an item to a test project.

Create Templates to Jumpstart Development

To create a project item template, create the stubbed source file and an XML file with a .vstemplate extension. The XML file describes your template to the IDE. Place all of the code files and the .vstemplate file in a zipped file and move it to the \My Documents\Visual Studio\ItemTemplates\Visual Basic\ folder, and it is ready to use.

Creating templates can help jumpstart application development and make it much easier to use even the most advanced features of Visual Studio and Visual Basic. In 2005, this process is even easier.

About the Author

Paul Kimmel is the VB Today columnist for www.codeguru.com and has written several books on object-oriented programming and .NET. Check out his book Visual Basic .NET Power Coding from Addison-Wesley and his upcoming book UML DeMystified from McGraw-Hill/Osborne (Spring 2005). Paul is also the founder and chief architect for Software Conceptions, Inc, founded 1990. He is available to help design and build software worldwide. You may contact him for consulting opportunities or technology questions at pkimmel@softconcepts.com.

If you are interested in joining, sponsoring a meeting, or posting a job, check out www.glugnet.org, the Web page of the Greater Lansing area Users Group for .NET.

Copyright © 2005 by Paul T. Kimmel. All Rights Reserved.