Templates in Visual Studio 2005: Part 1, Item Templates

Templates in Visual Studio 2005 Part 1: Item Templates

09-August-2004

There’s a reason that I’m a geek trapped in a fat man’s body: I’m lazy; that may be why I like computers. Computers are great at doing a bunch of work for you. Even as a programmer there is still a lot of stuff that I do by hand, I find. With Visual Studio 2005, it looks like there may be an easy way to write a lot of boilerplate code only once. Some of the new features in VS2005 are Item Templates and Project Templates that are actually human readable.

Visual Studio 2003 Project Templates…

…might as well not exist. To write them, you had to do some hunting in the obscure bowels of the Visual Studio Program Files directory and edit these arcane vsdir and vsz files with text that C-3PO [Ed. This is the geek screaming to get out] might have trouble deciphering. There is an article on CodeProject that explains the whole process in straightforward fashion. (http://www.codeproject.com/dotnet/AddingTemplatesAddBox.asp)

Fortunately, Microsoft made it a lot easier to do this is Visual Studio 2005. For the remainder of the article, I’ll explain the process by adding an item Template for a Test Fixture from NUnit (http://www.nunit.org).

Note: For the rest of this article, I assume you have NUnit 2.2 or greater installed; all of this is done with VS2005 C# Express Beta. It is unlikely to change very much, but it might, so if it doesn’t work, figure it out.

Download the files discussed in this article.

What you get out of the box

A good place to start is to see what is provided for you when VS is installed. This requires searching those obscure directories in Visual Studio Program Files directory, but it’s worth the effort this time. If you browse to [Program Files]\Visual Studio 8\Common7\IDE\VCSExpress, you’ll see a several folders of note:

The one we want right now is the ItemTemplates folder. If you open that folder, you’ll see another folder called 1033, the folder for assemblies with English text. There may be more in there, depending on how many languages you have installed. Open that, and you’ll see a list of .zip files. Open Class.zip. You’ll see it contains two files: Class.cs and Class.vstemplate file. The vstemplate file is the one that does the main work, but before we look at that, let’s look at the Class.cs file.

Open it up in VS2005 and you get this:

#region Using directives

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

#endregion

namespace $rootnamespace$
{

	public class $safeitemrootname$
	{
		public $safeitemrootname$()
		{

		}

	}

}

If you’ve been using VS2005 for a while, you’ll recognize this as the default code when you add a new Class1.cs file to your project. The placeholders $rootnamespace$ and $safeitemrootname$ are replaced with the Namespace name and class name respectively when you click OK in the new file dialog.

Fixture.cs

Now that we have this open, let’s modify it to create our fixture class, like so:

#region Using directives

using System;
using System.Collections.Generic;
using System.Text;
using NUnit.Framework;

#endregion

namespace $rootnamespace$
{
	[TestFixture]
	public class $safeitemrootname$
	{
		[SetUp]public void Init()
		{

		}

		[TearDown]public void TearDown()
		{

		}

		[Test]public void Test1()
		{

		}

	}

}

Save this file Fixture.cs. As you can see, I’ve added the using directive for NUnit.Framework and added the attributes and methods that I want. There isn’t anything fancy about a Test Fixture, so I have only the placeholders we saw above. Now we can take a look at the vstemplate file that we want to go along with this file.

VS Template Files

The former obscure vsdir and vsz files have been replaced with .vstemplate files. Essentially, they are XML files with a schema. The schema is located in the VS2005 Program Files directory (Surprise!) under \xml\schemas\ItemTemplate.xsd. All vstemplate files must have the following format:

<VSTemplate Version="1.1.0" Type="Item">
	<TemplateData>
		<Name>
		<Description>
		<Icon>
		<ProjectType>
			<Languages>
				<Language>
			</Languages>
		</ProjectType>
		<SortOrder>
		<DefaultName>
	</TemplateData>
	<TemplateContent>
		<References>
			<Reference>
				<Assembly>
			</Reference>
		<ProjectItem>
			<SourceFile>
			<ReplaceParameters>
		</ProjectItem>
	</TemplateContent>
</VSTemplate>

<VSTemplate>

This is the root node and require the version and type elements as above.

<TemplateData>

This contains all the data for the template:

<Name>, <Description> and <Icon>

The name, the name of the type of file, i.e. Test Fixture; and description nodes are required and can have one of two child elements: <String>, for a name and description right in the file, or <Package>, where you’d have the name and description in a resource file, presumably so that you can add other languages easily. If you look at Class.vstemplate, you’ll see an example of the <Package> element.

The <Icon> element describes the icon to display in the file chooser for the file. It can have <Package> or <FilePath>. If I was adventurous, I’d extract the Nunit icon and show that, but for now, I’ll keep the <Package> element as it is, so our vstemplate file looks like this:

<VSTemplate Version="1.1.0" Type="Item">
	<TemplateData>
		<Name>
			<String>Test Fixture</String>
		</Name>
		<Description>
			<String>Create a unit test fixture</String>
		</Description>
		<Icon>
			<Package GUID="{FAE04EC1-301F-11d3-BF4B-00C04F79EFBC}" ID="4515"/>
		</Icon>

<ProjectType>,<Languages>,<Language>

The project type contains only the languages element, which in turn contains only the language element. For this project type, we want the C# language. So we want the following ProjectType element:

		<ProjectType>
			<Languages>
				<Language>CSharp</Language>
			</Languages>
		</ProjectType>

<SortOrder>, <DefaultName>

SortOrder is an integer that determines where in the file chooser dialog it shows. From what I can see, it starts at 10 (Form.cs) and moves up from there. It doesn’t matter what we put in at the moment for reasons that I’ll explain. DefaultName is the default name for the file. With those additions we complete the TemplateData section.

		<SortOrder>20</SortOrder>
		<DefaultName>Fixture</DefaultName>
	</TemplateData>

There are other optional elements that appear to deal with Master pages and some more ASP.NET 2 what not, so we’ll leave those out. To see what they do, refer to the schema.

<TemplateContent>

This element contains the information for the content that the IDE will use when it creates the file.

<References>,<Reference>,<Assembly>

These elements describe the references required for this file. By default, projects include System, System.Xml, and System.Data, but they are usually included the template file anyway. We want to refer to NUnit.Framework to make sure it gets included. The Assembly element contains the strong name for the assembly. Our TemplateContent will start as follows:

	<TemplateContent>
		<References>
			<Reference>
				<Assembly>System, Version=2.0.3600.0, Culture=neutral, PublicKeyToken=b77a5c561934e089</Assembly>
			</Reference>
			<Reference>
				<Assembly>System.Data, Version=2.0.3600.0, Culture=neutral, PublicKeyToken=b77a5c561934e089</Assembly>
			</Reference>
			<Reference>
				<Assembly>System.XML, Version=2.0.3600.0, Culture=neutral, PublicKeyToken=b77a5c561934e089</Assembly>
			</Reference>
			<Reference>
				<Assembly>NUnit.Framework, Version=2.1.93.0, Culture=neutral, PublicKeyToken=96d09a1eb7f44a77</Assembly>
			</Reference>
		</References>

<ProjectItem>

This contains filename of the template file, Fixture.cs in our case. There are some optional elements here that we want to use as well. Remember the placeholders in the template file? We want to replace them with actual values for the created file so we’ll set the ReplaceParameters element to true:

		<ProjectItem>
			<SourceFile>Fixture.cs</SourceFile>
			<ReplaceParameters>true</ReplaceParameters>
		</ProjectItem>

That ends off the TemplateData element as well as the VSTemplate element.

Loading our Template

We’re almost ready to use our template. Save the vstemplate file in the same directory as the Fixture.cs file. Create a zip file with both of them called Fixture.zip. Now, we could put it in the ItemTemplates directory under the VS2005 Program Files directory, but that’s usually not recommended for user template. A better place to put it would be in the Visual Studio folder in My Documents. If you go there, you’ll see way more folders there than there were for previous versions. The folder we want is ItemTemplates, and finally Visual C# Projects. Drop the zip file in that folder and then load Visual Studio. Create a new project and right-click to add a new file. There you’ll see our new template for a test fixture. Click here for image.

Conclusion

If you were brave enough to read up on how it was done in previous versions of Visual Studio, you’ll see how easy it is to set up code templates. This can be a huge time savings with all the boilerplate code you won’t have to write.

Just don’t tell your boss about this. 🙂

Part 2 will cover Project Templates.