Inside Microsoft® Visual Studio® .NET 2003 [Electronic resources] نسخه متنی

Creating the Wizard Object

Every wizard, whether it is a New Project wizard, an Add New Item wizard, or a Custom wizard, is simply a COM object that implements the EnvDTE.IDTWizard interface. Execute, the only method of this interface, is called when Visual Studio .NET loads the wizard. The signature for this interface is

public interface IDTWizard
{
public void Execute(object Application, int hwndOwner, 
ref object[] ContextParams, 
ref object[] CustomParams, 
ref EnvDTE.wizardResult retval)
}

A number of arguments are supplied to the Execute method:

Application

The DTE object for the instance of Visual Studio .NET in which the wizard is being run

hwndOwner

A handle to a window that the wizard can use as a parent for any user interface elements that the wizard creates

ContextParams

An array of type object that describes the state Visual Studio .NET is in when the wizard is run

CustomParams

An array of type object containing data defined by the wizard writer and passed to the wizard object

The Execute method is where all the processing for a wizard takes place. Within this method, a wizard has complete control over how it performs its work. Visual Studio .NET places no restrictions on how a wizard is implemented other than that it must implement the IDTWizard interface on a COM object. A wizard can display a user interface to ask the user questions, or it can use the information provided through the various arguments of the Execute method to perform its work. You can think of the Execute method as similar to the Main function of a Visual Basic or Visual C# console application: once called, it can do whatever it wants.

The ContextParams argument passed to Execute is an array of elements that's populated with values the user enters in the Add New Item or New Project dialog box. It also contains a number of other values, provided by Visual Studio .NET, that give hints to your wizard about how it should generate code. The values in the array change depending on whether the wizard is run as a New Project wizard, an Add New Item wizard, or a Custom wizard. The arguments for the various project types and the order in which those types appear are listed in Table 9-1 and Table 9-2.

We didn't include a table that lists context parameters for a Custom wizard because these are not determined by Visual Studio .NETthey're supplied by an add-in, a macro, or even another wizard. We'll discuss the Custom wizard type and the CustomParams that Custom wizards are passed in more detail later in this chapter.

When run, a wizard should verify that the first element of the context parameter array is the constant EnvDTE.Constants.vsWizardNewProject if the wizard is a New Project wizard or the constant EnvDTE.Constants.vsWizardAddItem if the wizard is an Add New Item wizard. If the GUID doesn't match the type of wizard the object implements, the object should return the error code wizardResult.wizardResultFailure through the retval argument of IDTWizard.Execute.

Note

When you check the GUID that is passed as the wizard type, you should perform a case-insensitive comparison because the constants vsWizardNewProject and vsWizardAddItem might have a different case than any value passed from Visual Studio .NET as the first value in the ContextParams array.

An example implementation of a wizard and the code to extract the elements from the ContextParams array are shown in Listing 9-1.

Listing 9-1 The wizard add-in source code

Wizard.cs
using System;
using System.Runtime.InteropServices;
namespace BasicWizard
{
[GuidAttribute("E5D0A8B2-A449-4d3b-B47B-99494D23A58B"), 
ProgIdAttribute("MyWizard.Wizard")]
public class Wizard : EnvDTE.IDTWizard
{
public void Execute(object Application, int hwndOwner, 
ref object[] ContextParams, 
ref object[] CustomParams, 
ref EnvDTE.wizardResult retval)
{
EnvDTE.DTE application = (EnvDTE.DTE)Application;
string wizardType = (string)ContextParams[0];
if(System.String.Compare(wizardType, 
EnvDTE.Constants.vsWizardNewProject, true) == 0)
{
string newProjectName = (string)ContextParams[1];
string newProjectLocation = (string)ContextParams[2];
string visualStudioInstallDirectory = 
(string)ContextParams[3];
bool exclusiveProject = (bool)ContextParams[4];
string newSolutionName = (string)ContextParams[5];
bool runSilent = (bool)ContextParams[6];
}
else if(System.String.Compare(wizardType, 
EnvDTE.Constants.vsWizardAddItem, true) == 0)
{
string projectName = (string)ContextParams[1];
EnvDTE.ProjectItems projectItems = 
(EnvDTE.ProjectItems)ContextParams[2];
string newItemLocation = (string)ContextParams[3];
string newItemName = (string)ContextParams[4];
string productInstallDirectory = (string)ContextParams[5];
bool runSilent = (bool)ContextParams[6];
}
else
{
//ERROR! Unknown wizard type
}
}
}
}