Walkthrough: Creating a Wizard

Article
02/21/2013

Wizards, such as the Add-in Wizard, are programs that lead a user through a series of actions to accomplish a complex, repetitive, or difficult task. Windows, for example, uses wizards to connect to network resources, connect to printers, and so forth.

In Visual Studio, wizards generally ask a series of questions that solicit input from a user, and then use the results to generate code. Wizards, however, do not always display a user interface (UI). They can be programmed to invisibly generate code behind the scenes.

There are three different types of wizards.

New Project wizards — As the name suggests, these wizards are used to generate new code for a particular type of project, giving the user a starting point from which to add their own code. This is the most commonly used type of wizard.
Add New Item wizards — These wizards are used to add new items, such as Web forms, text files, HTML pages, XML pages, and so forth, to a project.
Custom wizards—These wizards are not called from a dialog box. Instead they are called directly from add-ins, macros, or other types of code. They may or may not display a UI. In either case, they generate code. This type of wizard is used the least often.

Regardless of the type of wizard, they all have common traits.

They are .NET objects that implement the IDTWizard interface and have an associated method, Execute, which contains the code you want the wizard to run.
They all use a .vsz file to display themselves in Visual Studio.
They all generate code or perform some other task.

You can customize the appearance of elements in wizards that you create. Wizards most often consist of one or more windows, or pages. Pages can contain a descriptive image, such as on the top or to the left side of the page, a label description, instructions, and an area in which navigation controls such as Next and Previous can be placed.

The process for creating wizards in Visual C++ is a bit different from creating standard Visual Studio wizards. For additional information about creating wizards targeted to Visual C++, see Designing a Wizard and Creating a Custom Wizard.

Note

The dialog boxes and menu commands you see might differ from those described in Help depending on your active settings or edition. These procedures were developed with the General Development Settings active. To change your settings, choose Import and ExportSettings on the Tools menu. For more information, see Visual Studio Settings.

An Example of a Basic Wizard

Visual Studio Add In Wizard

This picture shows a panel of the Add-In Wizard, a New Project type of wizard which leads you through a series of steps to create an add-in. You can customize the appearance of your wizards, but the Add-In Wizard is a good example of the style of a standard type of wizard. Completed wizards become available templates in the New Project or Add New Item dialog boxes.

The following demonstrates how to create a basic wizard and optionally give it a custom icon.

To create a basic wizard in Visual Basic and Visual C#

Run Visual Studio as an Administrator. Registering the wizard requires updating the registry, so it needs this privilege.
Create a new Class Library project named MyNewWizard.
Add references to EnvDTE and EnvDTE80 to the project.

To do this, right-click the project and click Add Reference. In the .NET tab of the Add Reference dialog, click EnvDTE and EnvDTE80 and then click OK.

In the class module, include references to EnvDTE and EnvDTE80 and implement the IDTWizard interface. For this Visual C# example, you must also add a reference to System.Windows.Forms and System.Runtime.InteropServices.

Imports EnvDTE 
Imports EnvDTE80
Public Class Class1
    Implements IDTWizard

using System;
using System.Collections.Generic;
using System.Text;
using EnvDTE; 
using EnvDTE80; 
using System. Windows.Forms;

using System.Runtime.InteropServices;

namespace MyNewWizard
{

[ComVisible(true)]

[Guid("20184B81-7C38-4E02-A1E3-8D564EEC2D25"),

ProgId("MyNewWizard.Class1")]

    public class Class1 : IDTWizard
    {
    }
}

When you add the Implements statement to Visual Basic, position the cursor at the end of the line and press enter to automatically create an Execute method procedure. For Visual C#, however, you must add the Execute procedure manually:

public class Class1 : IDTWizard
    {
    public void Execute(object Application,  
        int hwndOwner, ref object[] contextParams,  
        ref object[] customParams,  
        ref EnvDTE.wizardResult retval)

Add the code you want the wizard to run to the Execute procedure. For this example, we will just add a simple message box.

You should have the following:

Imports EnvDTE
Imports EnvDTE80

Public Class Class1
    Implements IDTWizard

    Public Sub Execute(ByVal Application As Object, ByVal _
    hwndOwner As Integer, ByRef ContextParams() As Object, ByRef _
    CustomParams() As Object, ByRef retval As EnvDTE.wizardResult) _
    Implements EnvDTE.IDTWizard.Execute
        MsgBox("The wizard is now running.")
    End Sub
End Class

using System.Text;
using EnvDTE;
using EnvDTE80;
using System.Windows.Forms;
using System.Runtime.InteropServices;

namespace MyNewWizardCS
{
    public class Class1 : IDTWizard
    {

    public void Execute(object Application, 
        int hwndOwner, ref object[] contextParams, 
        ref object[] customParams, 
        ref EnvDTE.wizardResult retval)
    {
        MessageBox.Show("The wizard is now running.");
    }
}

}

The Execute procedure is called when the wizard is started.

Right-click your project in Solution Explorer and click Properties to open the Project Properties page, click the Build tab, and then check the Register for COM interop box at the bottom of the page.
In the AssemblyInfo.cs file, find the ComVisible attribute and set it to true.
Build the project to create the class library dll by clicking Build Solution on the Build menu.
Create a .vsz text file for the wizard named MyNewWizard.vsz.

To do this, make a copy of an existing .vsz file, such as any of those located at <Visual Studio Install Directory>\VC#\CSharpProjectItems\Windows Forms, and rename it "MyNewWizard.vsz".

A .vsz file is a text file that enables Visual Studio to recognize the wizard and display it in the New Project or Add New Item dialog boxes. The Wizard parameter should be set to the progID (Project.Classname) of the project or the GUID. For more information, see Configuring .Vsz Files to Start Wizards.

Note

Optionally, you can also create a VSDir file for the wizard. This contains the information that displays as a description for the wizard in the AddNew Project or AddNew File dialog boxes. It also allows you to specify an icon and arrange its location in the list. For more information, see Adding Wizards to the Add Item and New Project Dialog Boxes by Using .Vsdir Files.

Replace the contents of MyNewWizard.vsz with the following:

VSWizard 7.0
Wizard=MyNewWizard.Class1
Param=First Item
Param=Second Item

Save the new .vsz file in the directory where you want the wizard to appear.

For this example, we want the wizard to appear in the Add New Item dialog box for Visual Basic projects, so save the .vsz file in the following directory: <Visual Studio Install Directory>\VB\VBProjectItems.
Exit Visual Studio and then restart it.

This forces Visual Studio to read the new .vsz file.
Create a new Visual Basic project, such as a Windows Application project.
Right-click the project, point to Additem, and then click New Item.

You should see your new wizard (MyNewWizard) in the Add New Items dialog box.
Click the wizard and click the Add button.

You see the message, "The wizard is now running."

To display a custom icon for the new wizard

Place an icon file with the same base file name as the .dll file but with an .ico extension in the same directory as the wizard file.

For example, if the wizard is named MyNewWizard.dll, name the .ico file MyNewWizard.ico.

-or-
If you have created a VSDir file, specify a path to the icon (.ico) file there.

Walkthrough: Creating a Wizard

An Example of a Basic Wizard

To create a basic wizard in Visual Basic and Visual C#

To display a custom icon for the new wizard

See Also

Tasks

Reference

Concepts

Other Resources

Additional resources