Building VS.NET Wizards Part 2

Contents

• Creating your own wizard
• Introduction
• Creating a .vsdir file
• Setting up the .vsz file
• Some final words
• Summary
• References

Creating your own wizard

In Part 1 of this series, you already learned how to extend the Add New Class template file already shipped with Visual Studio .NET 2003. But when you are creating test classes using NUnit or TestDriven.NET, you might want to have a skeleton class, which adds the [TestFixture] attribute to the class declaration and which defines a method already having the [Test] attribute added to it. Additionally you would appreciate that you can select this template from the "Add new element" wizard page.

Introduction

This article will explain how you can easily create your own wizards doing just a few steps. Again, I want to refer the really good article Creating project item code templates for Visual Studio .NET by Emil Aström. I suggest that you read this article carefully because I will crosslink to it, whenever I feel it is necessary.

The background - or intention - this time will be to create a skeleton class for NUnit test cases. This skeleton class is based on the template we created in Part 1 and extends it. So if you have passed Part 1, then I suggest to read this article now.

Creating a .vsdir file

The first step you'll have to do is to create a new .vsdir file. The format of the file is explained in Emil's article. If you installed Visual Studio .NET 2003 using default options, you will find the directory where to create the .vsdir file at:

C:\Program Files\Microsoft Visual Studio .NET 2003\VC#
       \CSharpProjectItems\LocalProjectItems

for C# projects. If you changed the installation path, you can look at Emil's article to get the correct path to your project items directory. If you want to, you can add a new category by simply creating a new directory at this location. Try it and add the new directory:

C:\Program Files\Microsoft Visual Studio .NET 2003\VC#
      \CSharpProjectItems\LocalProjectItems\Wizardry

In the new directory, add a file called called wizardry.vsdir. Open the file in an editor and add the following pipe delimited string to it:

..\..\CSharpAddNunitTestClass.vsz|0|NUnit Testclass|1|Creates 
                           a new NUnit Testclass|0|0|0|TestClass.cs

Please ignore the line break above that has been added here to avoid text from scrolling.

Here's a brief description of the content (thanks Emil). You will also find a complete documentation in MSDN:

• RelPathName - relative path to the item's .vsz file.
• (clsidPackage) - optional GUID for a component containing localized resources.
• LocalizedName - the name of the project item to display in the Add New Item dialog.
• SortPriority - a number that decides the relative order of items in the Add New Item dialog.
• Description - a description of the project item is displayed in the status field for the Add New Item dialog.
• DllPath or (clsidpackage) - a path or GUID of a DLL that contains an icon resource to use for the item.
• IconResourceId - the resource ID of the icon contained in the component given by the above parameter.
• Flags - combined value of flags to use.
• SuggestedBaseName - the base file name to use for the item.

The .vsz files shipped with Visual Studio .NET 2003 are normally kept in the CSharpProjectItems directory, so I decided to put mine there too. But you can place them anywhere you want, all you have to do is to setup the parameter RelPathName correctly to point to the location of the file.

Important note: Don't put a line break in the middle of the pipe delimited set of parameters. Otherwise this will cause your wizard not to work!

Setting up the .vsz file

The .vsz file directed to by the RelPathName parameter contains information about the component to use to create the project item. In this article, we will create a project item using the standard engine called VsWizard.VsWizardEngine.7.1. But in the last part of this series you will learn how to create your own engines.

In the directory,

C:\Program Files\Microsoft Visual Studio .NET 2003\VC#\CSharpProjectItems\

add a new file called CSharpAddNUnitTestClass.vsz. If you change the relative path in the .vsdir file, you will have to add the file at the directory you pointed to. Open the file in an editor and add the following content:

VSWIZARD 7.0
Wizard=VsWizard.VsWizardEngine.7.1
Param="WIZARD_NAME = CSharpAddNunitTestClassWiz"
Param="WIZARD_UI = FALSE"
Param="PROJECT_TYPE = CSPROJ"

The parameter VSWIZARD 7.0 identifies the expected version, so you should not change it. The other parameters are covered in Emil's article and there is nothing more to tell about them.

A lot more other parameters can be changed in the .vsz file, but we can ignore them right now. I just want to mention two interesting things:

1. The parameter ABSOLUTE_PATH can direct to the directory containing the wizard files we will create in the next step. If this parameter is not found, the wizard files are searched using the RELATIVE_PATH parameter which directs to C:\Program Files\Microsoft Visual Studio .NET 2003\VC#\VC#Wizards\ for C# projects. The name of the wizard (WIZARD_NAME) is then added to this path and the files are expected there (this is for us C:\Program Files\Microsoft Visual Studio .NET 2003\VC#\VC#Wizards\CSharpAddNUnitTestClassWiz\).
2. You can add your own parameters to the .vsz files which you might require later in the C# templates or scripts by just adding it to the file: Param="MYPARAM = myvalue".

Documentation for all already available parameters can be found in MSDN.

Creating the template file

Remember, back in Part 1, we edited the template file of the Add New Class wizard. We added some code comments and regions to it, saved it, and after restarting Visual Studio .NET 2003, we got the expected result. As I already mentioned before, the path to the template files is defined by two variables (when not adding the ABSOLUTE_PATH parameter to the .vsz file):

1. The RELATIVE_PATH which directs to the VC#Wizards subdirectory.
2. The name of the wizard we set using the parameter WIZARD_NAME.

So our files are expected (if you installed Visual Studio .NET 2003 at the default location) at:

c:\Program Files\Microsoft Visual Studio .NET 
             2003\VC#\VC#Wizards\CSharpAddNUnitTestClassWiz\

Create this directory and copy the contents of CSharpAddClassWiz directory from Part 1 into the new directory. Open the file NewCSharpFile.cs and change its contents:

using System;
using System.Diagnostics;

using NUnit.Framework;

namespace [!output SAFE_NAMESPACE_NAME]
{
    /// <summary>
    /// Comments for [!output SAFE_CLASS_NAME].
    /// </summary>
    /// <remarks>
    /// <para>created: [!output CREATION_DATE]</para>
    /// <para>Author : Michael Groeger</para>
    /// </remarks>
    [TestFixture]
    public class [!output SAFE_CLASS_NAME]
    {

    #region [!output SAFE_CLASS_NAME]  Testcases

        /// <summary>
        /// Comments for Test().
        /// </summary>
        [Test]
        public void Test()
        {
            // TODO: add test instructions here
        }

    #endregion

    }
}

Save the file and run a new instance of Visual Studio .NET 2003. Open a project, right click on its project name in Solution Explorer and click "Add > Add class". The wizard dialog opens and you should see the following:

If you click Open, the following class should be generated for you:

using System;
using System.Diagnostics;

using NUnit.Framework;

namespace Wizardry2
{
    /// <summary>
    /// Comments for TestClass1.
    /// </summary>
    /// <remarks>
    /// <para>created: 10. May 2005</para>
    /// <para>Author : Michael Groeger</para>
    /// </remarks>
    [TestFixture]
    public class TestClass1
    {

    #region TestClass1  public members

        /// <summary>
        /// Comments for Test().
        /// </summary>
        [Test]
        public void Test()
        {
        
        }

    #endregion

    }
}

Some final words

Unfortunately, I don't have an English version of Visual Studio .NET. So the screenshots in this article are kept in German. If somebody wants to, he can send me English screenshots. The paths in this article should be correct for English versions, if not, just leave me a note.

Summary

This time I have shown you that it is very easy to create your own wizards which produce skeleton classes for simple purposes. It has just taken a few steps:

• Create a new .vsdir file.
• Create a new .vsz file.
• Create your own template.

The next article will cover, how you can add a simple user interface to your custom wizard, which allows you to add your own symbols. This will help you in creating typed collections and dictionaries. Interested? Coming soon...

References

• Creating project item code templates for Visual Studio .NET.
• Customizing Visual Studio's Code Generation Templates.
• VSDir Files.
• Custom Parameters in the Wizard .vsz File.

About Michael Groeger

We are working as freelancers in software engineering and consulting since september 2004. We worked as consultant before that for 5 years developing on windows platforms and since Beta 2 using .NET. We appreciate movies, music, football, billard, bowling and our queen. You will be assimilated! Resistance is futile! Click here to view Michael Groeger's online profile.