Building VS .NET Wizards - Part 1

Contents

• It's a kind of magic
• Introduction
• Summary
• References

It's a kind of magic

Go on! Run Visual Studio and create a new project in any language you desire, e.g. C#. What happens once you click Ok? It's a kind of magic... Visual Studio creates a new project for you and adds an empty class to that project. Visual Studio brings a lot of nice wizards which help you in developing large projects - but is that enough?

I decided to say No! So get your crystal ball and see the magic reveal...

Introduction

This is the first article of a series of four, I have decided to write. It covers a way to adjust the wizards which are already defined. There are several other resources even here at CodeProject which explains the same subject. I've added them to the References section at the end of this article. One really good article is the "Creating project item code templates for Visual Studio.NET" by Emil Aström, so I don't want to cover the terms described in this article again.

A few things the developers should always do is to document and test their code. Code documentation is done easily with C# using code documentation tags and can even be brought to great readable format using tools such as NDoc. Testing can be done using NUnit or TestDriven.NET which is a great add-in for Visual Studio.

So some steps you would normally do, while creating new classes is to add code comments to your classes, which will include the date, time and author of the class in the <remarks> section of your code comment. This would normally apply to the default constructor which is created for you. Maybe you would also like to add some regions to your class for your fields, properties, constructors and methods?

using System;
using System.Diagnostics;
namespace Wizardry1
{
    /// <summary>
    /// Comments for Class1.
    /// </summary>
    /// <remarks>
    /// <para>created: 5.May 2005</para>
    /// <para>Author  : Michael Groeger</para>
    /// </remarks>
    public class Class1
    {

        #region Class1 fields
        // add private fields here
        #endregion
        #region Class1  properties
        // add properties here
        #endregion
        #region Class1 constructors
        /// <summary>
        /// Constructor.
        /// </summary>
        /// <remarks>
        /// <para>created: 5.May 2005</para>
        /// <para>Author  : Michael Groeger</para>
        /// </remarks>
        public Class1()
        {
            //
            // TODO: Add constructor logic here
            //
        }
        #endregion
        #region Class1  public members
        // add public members (properties/methods) here
        #endregion
        #region Class1  private members
        // add private members (properties/methods) here
        #endregion
    }
}

Adjusting the class template

The class template

When you add a new class to your project using the Visual Studio wizard the skeleton class is created from a template, which can be found at, C:\Program Files\Microsoft Visual Studio .NET 2003\VC#\VC#Wizards\CSharpAddClassWiz\Templates\1033\, called NewCSharpFile.cs. It should look something like this:

using System;
namespace [!output SAFE_NAMESPACE_NAME]
{
    /// <summary>
    /// Zusammenfassung für [!output SAFE_CLASS_NAME].
    /// </summary>
    public class [!output SAFE_CLASS_NAME]
    {
        public [!output SAFE_CLASS_NAME]()
        {
            //
            // TODO: Fügen Sie hier die Konstruktorlogik hinzu
            //
        }
    }
}

Remarks: The subdirectory 1033 has the localized versions of the template for US-English.

SAFE_NAMESPACE_NAME and SAFE_CLASS_NAME are placeholders for the namespace and the class name respectively. These will be replaced by the wizard with the class name you set and the namespace the new class will correspond to. Now we want to adjust the template a little bit.

Adding some code comments

Backup the class template NewCSharpFile.cs and then open a copy of it and save it under NewCSharpFile.cs again. Open the template in Visual Studio and add some comments and region to it as follows:

using System;
namespace [!output SAFE_NAMESPACE_NAME]
{
    /// <summary>
    /// Comments for [!output SAFE_CLASS_NAME]
    /// </summary>
    /// <remarks>
    /// <para>created: [!output CREATION_DATE]/para>
    /// <para>Author  : Your name goes here</para>
    /// </remarks>
    public class [!output SAFE_CLASS_NAME]
    {
 
        #region [!output SAFE_CLASS_NAME] fields
        // add private fields here
        #endregion
        #region [!output SAFE_CLASS_NAME]  properties
        // add properties here
        #endregion
        #region [!output SAFE_CLASS_NAME] constructors
        /// <summary>
        /// Constructor.
        /// </summary>
        /// <remarks>
        /// <para>created: [!output CREATION_DATE]</para>
        /// <para>Author  : Your name goes here</para>
        /// </remarks>
        public [!output SAFE_CLASS_NAME]()
        {
            //
            // Add constructor logic here
            //
        }
        #endregion
        
        #region [!output SAFE_CLASS_NAME]  public members
        
        // add public members (properties/methods) here
        
        #endregion
        
        #region [!output SAFE_CLASS_NAME]  private members
        
        // add private members (properties/methods) here
        
        #endregion                
        
    }
}

Save the file and start another instance of Visual Studio. Open a project and add a new class using the wizard. The class that is generated now, should look like this:

using System;

namespace Wizardry1
{
    /// <summary>
    /// Zusammenfassung fr MyClass.
    /// </summary>
    /// <remarks>
    /// <para>erstellt: [!output CREATION_DATE]</para>
    /// <para>Author  : Michael Groeger</para>
    /// </remarks>
    public class MyClass
    {

        #region MyClass fields

        // add private fields here

        #endregion

        #region MyClass  properties

        // add properties here

        #endregion

        #region MyClass constructors

        /// <summary>
        /// Constructor.
        /// </summary>
        /// <remarks>
        /// <para>erstellt: [!output CREATION_DATE]</para>
        /// <para>Author  : Michael Groeger</para>
        /// </remarks>
        public MyClass()
        {
            //
            // TODO: Fgen Sie hier die Konstruktorlogik hinzu
            //
        }

        #endregion

        #region MyClass  public members

        // add public members (properties/methods) here

        #endregion

        #region MyClass  private members

        // add private members (properties/methods) here

        #endregion

    }
}

So the wizard did a wonderful job for you. But the placeholder CREATION_DATE was not replaced. CREATION_DATE is not part of the parameters the Visual Studio wizard comes along with. So you have to add it on your own.

Adding custom parameters

Beside the class template in the Templates subdirectory there is a JScript file called default.js at, C:\Program Files\Microsoft Visual Studio .NET 2003\VC#\VC#Wizards\CSharpAddClassWiz\Scripts\1033\.

Again 1033 has the localized versions for US-English. Here is the place where you can add your own parameters to the wizard. Adding parameters to the wizard is simply done by calling:

wizard.AddSymbol([SYMBOL], [VALUE]);

What we do now is to add the logic for adding the current date to the wizards parameters. Backup the JScript file and open it in Visual Studio. The JScript function for adding the date will look like this:

function CreationDate()
{
       var Months = new Array("January","February","March","April","May","June",
                "July","August","September","October","November","December");
    var myDate = new Date();
    var currentDate = myDate.getDate()
    +"."
    + Months[myDate.getMonth()]
    +" "
    +myDate.getFullYear();
    
    wizard.AddSymbol("CREATION_DATE",currentDate);
}

This is enough code to create and add the Date to the parameters of the wizard. All we have to do now is to add a call to our function in the OnFinish() function which is already defined:

function OnFinish(selProj, selObj)
{        
// [...]
    var strSafeProjectName     = CreateSafeName(strProjectName);
    wizard.AddSymbol("SAFE_PROJECT_NAME", strSafeProjectName);

    // add CreationDate() call    
    CreationDate();
    
    SetTargetFullPath(selObj);
    var strProjectPath    = wizard.FindSymbol("TARGET_FULLPATH");
    var strTemplatePath     = wizard.FindSymbol("TEMPLATES_PATH");
// [...]        
}

Save the JScript file and now try to add again a new class to your project using the class wizard. Now CREATION_DATE should be replaced by the current date:

/// <summary>
/// Comments for Class1.
/// </summary>
/// <remarks>
/// <para>created: 5.May 2005</para>
/// <para>Author  : Michael Groeger</para>
/// </remarks>

Summary

I have shown you that it is easy to adjust existing wizards to your own needs, by just doing a few steps. These steps are:

• edit the C# class template NewCSharpFile.cs.
• edit the JScript file default.js to add some new parameters.

In the next article I will explain, how you can easily create your own wizards.

References

• Creating project item code templates for Visual Studio .NET.
• Customizing Visual Studio's Code Generation Templates.