VC++ 自定义向导（如何生成，修改，调试自定义向导）

阳光穿透心脏的1/2处 2022-12-25 10:00 502阅读 0赞

这是一篇关于C++中自定义向导非常好的文档。

取自：[http://msdn.microsoft.com/en-us/library/aa730846(v=vs.80).aspx][http_msdn.microsoft.com_en-us_library_aa730846_v_vs.80_.aspx]

# Inside Visual C++ Wizards #

Shankar Vaidyanathan, Gabriel Esparza-Romero, Andras Tantos, Boris Jabes  
Microsoft Corporation

March 2006

Applies to:  
   Visual C++ .NET  
   Visual C++ .NET 2003  
   Visual C++ 2005

**Summary:** This article provides an inside look at the architecture of the Visual C++ wizards. From new projects to adding items, you will learn how to customize existing wizards and create your own. (20 printed pages)

#### Contents ####

[Introduction][]  
[Walkthrough of Wizard Execution][]  
[Delving into the Wizard Architecture][]  
[Writing a Custom Wizard][]  
[Conclusion][]

## Introduction ##

One of the most overlooked features of Visual Studio is its impressive array of wizards. We tend to start any project by running a wizard, and the code that we write afterwards is partly generated by wizards, as well. In the realm of C++ development, wizards automate a variety of tasks. For example, there are wizards that create projects based on MFC or .NET and help users get started and learn about appropriate compiler switches. Beyond these are wizards that automate some common coding tasks such as inserting a new MFC element.

All of the C++ wizards are built on top of a flexible wizard engine in Visual Studio. In other words, they are customizable and users can access the underlying functionality to create their own wizards. Indeed, exposing the internals and the UI of wizards is one of the fundamental design goals of the wizard engine. As such, the bulk of the intelligence resides within the wizards while our engine provides basic framework functionality.

Users can add new wizards to automate repetitive work or as part of a third party add-in to Visual Studio. These customized wizards can perform tasks as simple as filling in some fields, like a company name, or as complex as providing default implementations for custom interfaces.

**Table 1. Wizard types**

In this article we describe the VSWizard engine, which is designed to handle C++ wizards included in Visual Studio. Users can take advantage of this engine to write their own C++ wizards and thus gain productivity at low cost. The goal of this article is to explain how wizards work and provide a starting point to write new custom wizards.

## Walkthrough of Wizard Execution ##

### Populating the List of Project Templates Dialog ###

When a user opens the **New Project** dialog, the Visual Studio shell looks at all the installed project systems at the current machine under the following registry key:

**HKEY\_LOCAL\_MACHINE\\SOFTWARE\\Microsoft\\VisualStudio\\8.0\\Projects.**

The shell then enumerates through all the project types and queries for the ProjectTemplatesDir key to identify the location of all the New Project wizards for each project type. These directories are called template directories. The Visual C++ project templates directory in Visual Studio 2005 is obtained from the following registry key:

**HKEY\_LOCAL\_MACHINE\\SOFTWARE\\Microsoft\\VisualStudio\\8.0\\Projects\\\{8BC9CEB8-8B4A-11D0-8D11-00A0C91BC942\}\\ProjectTemplatesDir.**

The shell then reads all the wizard and directory description files (\*.vsz and \*.vsdir respectively) found in these directories. Each wizard is represented by a single wizard description file, which contains the basic information about the wizard. Each directory containing wizards must also have at least one directory description file, which describes how to present the wizards to the user. Using all this information, the shell displays a tree of all the available New Project wizards (Figure 1). The structure of the .vsz and .vsdir files is described later in this article.

![Aa730846.invcwiz01(en-US,VS.80).gif][Aa730846.invcwiz01_en-US_VS.80_.gif]

**Figure 1. New Project Dialog**

A similar dialog is used for the Add New Item and Add Class wizards. The template directories for these wizards are displayed by querying a different set of registry keys. Table 2 lists these keys and the Visual Studio 2005 template directories that they point to. In other words, these are the directories where .vsz and .vsdir files are stored.

**Table 2. Registry keys specifying location of wizards**

The Visual Studio 2005 Installation Directory is usually:

**<Program Files>\\Microsoft Visual Studio 8**

The **New Project, Add New Item,** and **Add Class** dialogs display an icon for each .vsz file that is found at the template directories. The icon is found in one of these two locations:

1.  From the same directory as the .vsz file. This requires that the icon file be named the same as the .vsz file.
2.  From the location specified in the .vsdir file.

### Launching a Wizard and Initializing the Context ###

When the user selects a wizard and clicks on the **OK** button in the relevant dialog, the Visual Studio shell uses the ProgID described in the second line of the corresponding wizard description file to create the **wizard engine**, which is a COM object. For C++ projects in Visual Studio 2005 the engine is called VSWizard and the ProgID is **VsWizard.VsWizardEngine.8.0.**This article deals only with this particular wizard engine. Note that this ProgID changes with each version of Visual Studio.

#### The Wizard Engine ####

The VSWizard engine provides the framework and utility functions that wizards can use. The wizard's user interface is primarily HTML. The back-end is JScript with full access to the rich object-model of Visual Studio. The VSWizard engine essentially coordinates the UI and runs the back-end script when the user clicks the **Finish** button on the wizard dialog. It also augments the object model with utility functions to provide functionality that would otherwise be complicated or inaccessible. For instance, the wizard engine exposes an API to bring up the**OleDB** dialog, which otherwise would not be available from script. Please see [VCWizCtl Object Properties, Methods, and Events][VCWizCtl Object Properties_ Methods_ and Events] in the MSDN library for the complete list of all the control's API.

#### The Symbol Table ####

The .vsz file can also contain parameters that will get passed to the wizard engine. These parameters can be used to customize the behavior of a wizard; thus the name custom parameters. Refer to the description of the .vsz file structure later in this article for more information.

When the VSWizard engine is instantiated, it creates a name/value pair collection called the symbol table to store these parameters and to keep track of all the user's choices in the UI. Values in this symbol table can be read and modified by the wizards, except for the 'context parameters' described later in this article.

In addition to the custom parameters specified in the .vsz file, the Visual Studio shell passes a few other parameters (listed in [Table 6][]) called context parameters that give details on the current project and the context in which the wizard is being run. They can only be set by the shell, but can be used anywhere in the wizard.

#### Locating the Wizard Files ####

Once the engine is initialized, it locates the wizard UI and script files as follows:

1.  It queries the shell to get the registry key for the product.
2.  It opens the setup subkey under this registry path.
3.  It retrieves the value of the PROJECT\_TYPE symbol, which is a custom parameter in the .vsz file. For C++, this value is **VCPROJ** and the wizard engine maps it to the registry key name 'VC.' This subkey is opened under the setup subkey. There is no such automatic mapping for third party languages, and so the PROJECT\_TYPE value is directly looked up under the setup subkey.
4.  The engine then queries for the **ProductDir** string value under this key. This value is saved as the PRODUCT\_INSTALLATION\_DIR symbol.
5.  The wizard engine looks for the existence of either the RELATIVE\_PATH or ABSOLUTE\_PATH symbols in the .vsz file. If the RELATIVE\_PATH symbol is found, then its value is appended to the product installation directory previously described. The wizard directory is located here. If the ABSOLUTE\_PATH symbol is present, then the product installation directory is ignored and the value of this symbol is used instead. If neither symbol is present, the default wizard location directory (VCWizards) name is added to the product installation directory path.
6.  Once the wizard engine has found the wizards directory, it determines the subdirectory in which the files for the wizard in question are located. This is found by appending the value of the **WIZARD\_NAME** parameter to the wizard's directory path. For instance, for the ATL OLEDB consumer class wizard, the ATLConsumer.vsz file contains the following line:
    
        Param="WIZARD_NAME = Consumer"
    
    So "Consumer" is the name of the directory in which the UI and script files are found. After the wizard directory has been determined, it is saved in the START\_PATH symbol for the wizard to use.

#### Layout of the Wizard Files ####

Inside the START\_PATH directory there are usually four directories: Html, Images, Scripts, and Templates. The Html directory is where the HTML files that specify the UI are stored. The Images directory is where the image files used in the UI are stored. The Scripts directory houses the script files used to control the wizard's behavior, and the Templates directory contains the template files that will be used by the wizard to produce its output.

Each wizard can have localized versions of files so that when the wizard is used in different locales (Japanese or German, for example), it will process the corresponding files. Thus, the actual files reside in subdirectories corresponding to each language codepage. Note that the Images directory does not have locale subdirectories, as similar graphics and icons tend to be used across all locales.

In addition, the wizard control uses the contents of **<VS Installation Directory>\\VC\\VCWizards\\<locale>** for the display and the execution of the wizard. All the common script functions are located in a file called common.js in this directory, as are all the HTML style sheets used to render the UI.

The locale is determined by the product language at installation time, but can be overridden by the /LCID command line option to devenv.exe.

### Executing the Wizard ###

Once the initialization is complete and the symbol table is filled in, the engine needs to determine if the wizard has a UI. This is done by checking the **WIZARD\_UI** parameter in the .vsz file. If it is set to **TRUE** or not specified at all, the engine opens a dialog and loads the main wizard HTML page (default.htm) from the corresponding wizard directory (**<START\_PATH >\\HTML\\<locale>**). The page uses the information in the symbol table to initialize its state (that is, default options currently selected) and adds symbols to the table based on the options chosen by the user. New values can be introduced to the symbol table with the **<symbol>** tag in the HTML file, or through JScript. Here is a quick example:

<SYMBOL NAME="CUSTOM_SYMBOL_1" TYPE="text" VALUE="My value"></SYMBOL>
 wizard.AddSymbol("CUSTOM_SYMBOL_2", "Another value");

The different values for the **TYPE** attribute for the SYMBOL tag are: **text, checkbox, radio,** and **bool.**

The HTML page can have links to other HTML pages. Before displaying the next page, however, the current one must save its state in the symbol table. All other state information will be lost. The symbol table acts as a repository of whatever the user has chosen thus far.

When the user clicks on a wizard's **Finish** button, the current HTML page's **OnFinish** method will be called. This method then usually calls **OnWizFinish** (declared in Common.js), which in turn calls the wizard engine's **Finish** method. This method will locate and load the wizard's default.js file in the **<START\_PATH>\\scripts\\<locale>** directory and call the **OnFinish** method in it. In short, this long chain of calls means that when users click on **Finish**, the **OnFinish** method in default.js gets executed.

In almost all cases, the core functionality of the wizard is in the **OnFinish** method inside the default.js file. User selection can be communicated to this script through the symbol table, which can be queried and modified using the **FindSymbol** and **AddSymbol** methods exposed on the wizard engine interface.

#### Common OnFinish Behavior ####

For New Project wizards, the actions in this OnFinish method are fairly standardized. They first create a project and then read the templates.inf file in the templates directory to determine what templates need to be parsed and added to the project. The files mentioned in templates.inf are optionally parsed, rendered, and added to the project based on the symbols set.

Both the templates.inf file as well as the templates themselves can use values in the symbol table to control the generated project. The details of this mechanism are described in the[Template Files][] section; it's sufficient to note here that parts of the templates can be excluded or included from the generated project depending on symbols being defined, and values of symbols can be embedded in the generated output, as well.

After parsing a template file, the function **GetTargetName** is called. This function is usually implemented in the wizard's default.js file and is used to assign a final name to the file generated from the template. For example, most application wizards have a template called root.cpp. This file, however, will assume the name of the project and will be saved as <project\_name>.cpp in the generated project.

After parsing, rendering, and adding the files to the project, the wizards typically set the corresponding project options, once again through script.

The Add New Item wizards use the same mechanism but only add files to existing projects.

Code wizards, on the other hand, are much more diverse and their actions in their **OnFinish** method highly depends on the purpose of the wizard, and in many occasion the existing project code.

## Delving into the Wizard Architecture ##

### Wizard Description File ###

The .vsz file extension denotes the wizard description files, which contain the information needed to launch a wizard. Each wizard must have one .vsz file.

* The first line is typically "VSWIZARD 7.0." The version here denotes the version of the file format and not the version of the product using the file.
 * The second line specifies the wizard's ProgID. In our case the second line is always the VSWizard ProgID: **Wizard=VsWizard.VsWizardEngine.8.0.**
 * The file can also contain one user defined custom parameters per line, with the format **Param="<PARAM\_NAME> = <PARAM\_VAL>.** Each custom parameter name and its corresponding value are added to the symbol table before displaying the wizard window or executing the wizard in case of UI-less wizards. "Custom parameters" is actually a misnomer, as some of the parameters, like WIZARD\_NAME, are required or have special meaning. The following parameters serve a special purpose in the wizard engine and thus their names are reserved (Table 3).

**Table 3. Built-in wizard symbols**

### Directory Description File ###

The .vsdir files are used to describe how wizard information will be presented to the user. They describe the wizards that will appear under the same branch of the **New Project** or **New Item** dialog. Each of these dialogs has a corresponding directory in which the .vsdir and .vsz files are stored.

For instance, when the user opens the Visual C++ **New Project** Dialog, the environment usually reads all the .vsdir files under the VCProjects directory to get information on which wizards are available. Please see [table 2][] for more information.

Each line of the .vsdir file identifies a wizard and must be terminated by an end of line character, including the last line of the file. Parameters must be in the order shown in Table 4 and must be separated by a pipe character (|). Optional parameters have to be replaced by a space if they are not specified.

**Table 4. Parameters in a vsdir entry**

**Table 5. VSDIR User Interface Flags**

You can find more information on the [VSDir Files][] page in the MSDN library.

### Symbol Table ###

The symbol table, as described previously, acts as a dictionary of all the information that the wizard will gather and use throughout its execution. Each symbol is made up of a case-sensitive name and a value. When the wizard is created, the symbol table contains the custom parameters specified in the .vsz file and a set of parameters based on the type of project. The wizards may then add more symbols depending on the user actions.

**Table 6. Symbols populated automatically by the wizard engine**

<table style="border-collapse:collapse; padding:0px; width:1097px; border:1px solid rgb(187,187,187)"> 
 <tbody> 
 <tr> 
 <th style="border:1px solid rgb(187,187,187); margin:10px; padding:10px 8px; background-color:rgb(237,237,237); color:rgb(112,112,112)"> Parameter Name</th> 
 <th style="border:1px solid rgb(187,187,187); margin:10px; padding:10px 8px; background-color:rgb(237,237,237); color:rgb(112,112,112)"> Description</th> 
 </tr> 
 <tr> 
 <td style="border:1px solid rgb(187,187,187); margin:10px; padding:10px 8px; color:rgb(42,42,42); vertical-align:top"> CLOSE_SOLUTION</td> 
 <td style="border:1px solid rgb(187,187,187); margin:10px; padding:10px 8px; color:rgb(42,42,42); vertical-align:top"> This symbol indicates whether the solution needs to be closed on the invocation of the wizard. For Project wizards its value depends on the options that the user specified in the&nbsp;New Project&nbsp;dialog; it is false for any other wizard types.</td> 
 </tr> 
 <tr> 
 <td style="border:1px solid rgb(187,187,187); margin:10px; padding:10px 8px; color:rgb(42,42,42); vertical-align:top"> DOCUMENT_FIRST_LOAD</td> 
 <td style="border:1px solid rgb(187,187,187); margin:10px; padding:10px 8px; color:rgb(42,42,42); vertical-align:top"> This symbol is set to true when wizard HTML page is loaded for the first time. HTML pages use this symbol to determine when to set its controls' value to its default state. This symbol is only set for wizards that have an HTML user interface.</td> 
 </tr> 
 <tr> 
 <td style="border:1px solid rgb(187,187,187); margin:10px; padding:10px 8px; color:rgb(42,42,42); vertical-align:top"> HTML_PATH</td> 
 <td style="border:1px solid rgb(187,187,187); margin:10px; padding:10px 8px; color:rgb(42,42,42); vertical-align:top"> The directory in which the wizard's HTML pages reside. Its value is formed based on the value of START_PATH. It includes the appropriate LangID subdirectory (the LangID is the product's language identifier, the engine retrieves it from the registry keyHKCU\Software\Microsoft\VisualStudio\8.0\General\UILanguage).</td> 
 </tr> 
 <tr> 
 <td style="border:1px solid rgb(187,187,187); margin:10px; padding:10px 8px; color:rgb(42,42,42); vertical-align:top"> IMAGES_PATH</td> 
 <td style="border:1px solid rgb(187,187,187); margin:10px; padding:10px 8px; color:rgb(42,42,42); vertical-align:top"> The location at which the wizard's image files are stored. Its default value is&nbsp;&lt;START_PATH&gt;\Images.</td> 
 </tr> 
 <tr> 
 <td style="border:1px solid rgb(187,187,187); margin:10px; padding:10px 8px; color:rgb(42,42,42); vertical-align:top"> ITEM_NAME</td> 
 <td style="border:1px solid rgb(187,187,187); margin:10px; padding:10px 8px; color:rgb(42,42,42); vertical-align:top"> For Add New Item wizards, it stores the name of the item to be added. It is undefined for other wizard types.</td> 
 </tr> 
 <tr> 
 <td style="border:1px solid rgb(187,187,187); margin:10px; padding:10px 8px; color:rgb(42,42,42); vertical-align:top"> PARENT_NAME</td> 
 <td style="border:1px solid rgb(187,187,187); margin:10px; padding:10px 8px; color:rgb(42,42,42); vertical-align:top"> When a Code wizard is invoked from a Class View code element, such as the Add Member Function wizard, this symbol stores the name of the parent object. For Add New Item wizards, it contains the name of the file to be added. It is undefined for all other wizards.</td> 
 </tr> 
 <tr> 
 <td style="border:1px solid rgb(187,187,187); margin:10px; padding:10px 8px; color:rgb(42,42,42); vertical-align:top"> PRODUCT_INSTALLATION_DIR</td> 
 <td style="border:1px solid rgb(187,187,187); margin:10px; padding:10px 8px; color:rgb(42,42,42); vertical-align:top"> The directory in which the product is installed. The product is determined by the PROJECT_TYPE custom parameter in the .vsz file. The value is obtained from the following registry key, where &lt;Product&gt; is any of the languages that are part of Visual Studio:HKLM\SOFTWARE\Microsoft\VisualStudio\8.0\Setup\&lt;Product&gt;\ProductDir.</td> 
 </tr> 
 <tr> 
 <td style="border:1px solid rgb(187,187,187); margin:10px; padding:10px 8px; color:rgb(42,42,42); vertical-align:top"> PROJECT_NAME</td> 
 <td style="border:1px solid rgb(187,187,187); margin:10px; padding:10px 8px; color:rgb(42,42,42); vertical-align:top"> Stores the name of the current project (or the project to be generated in the case of the Project wizards).</td> 
 </tr> 
 <tr> 
 <td style="border:1px solid rgb(187,187,187); margin:10px; padding:10px 8px; color:rgb(42,42,42); vertical-align:top"> PROJECT_PATH</td> 
 <td style="border:1px solid rgb(187,187,187); margin:10px; padding:10px 8px; color:rgb(42,42,42); vertical-align:top"> For Project wizards, this symbol represents where the project should be created; for all the other wizards, it represents the location at which the current project is located.</td> 
 </tr> 
 <tr> 
 <td style="border:1px solid rgb(187,187,187); margin:10px; padding:10px 8px; color:rgb(42,42,42); vertical-align:top"> PROJECT_TEMPLATE_PATH</td> 
 <td style="border:1px solid rgb(187,187,187); margin:10px; padding:10px 8px; color:rgb(42,42,42); vertical-align:top"> The directory in which the project templates exist. The project files for a particular language exist at this location. For instance, Visual C++ includes three different project templates (default.vcproj, defaultsql.vcproj, DefaultTest.vcproj) that the wizards use as a starting point to generate projects. Its value for Visual C++ is&nbsp;&lt;Program Files&gt;\Microsoft Visual Studio .NET\VC\VCWizards.</td> 
 </tr> 
 <tr> 
 <td style="border:1px solid rgb(187,187,187); margin:10px; padding:10px 8px; color:rgb(42,42,42); vertical-align:top"> SCRIPT_COMMON_PATH</td> 
 <td style="border:1px solid rgb(187,187,187); margin:10px; padding:10px 8px; color:rgb(42,42,42); vertical-align:top"> The directory in which the common wizard files are found (style sheets, images, and Common.js). Its value depends on the value of PRODUCT_INSTALLATION_DIR and includes the language identifier. For instance, its value for the English version of Visual C++ is&nbsp;&lt;Program Files&gt;\Microsoft Visual Studio .NET\VC\VCWizards\1033.</td> 
 </tr> 
 <tr> 
 <td style="border:1px solid rgb(187,187,187); margin:10px; padding:10px 8px; color:rgb(42,42,42); vertical-align:top"> SCRIPT_PATH</td> 
 <td style="border:1px solid rgb(187,187,187); margin:10px; padding:10px 8px; color:rgb(42,42,42); vertical-align:top"> This symbol identifies the directory in which the wizard's script files are located. The default value is&nbsp;&lt;START_PATH&gt;\Scripts\&lt;LangID&gt;, where LangID is the user interface language identifier.</td> 
 </tr> 
 <tr> 
 <td style="border:1px solid rgb(187,187,187); margin:10px; padding:10px 8px; color:rgb(42,42,42); vertical-align:top"> START_PATH</td> 
 <td style="border:1px solid rgb(187,187,187); margin:10px; padding:10px 8px; color:rgb(42,42,42); vertical-align:top"> The directory in which the wizard files reside. The wizard engine forms this directory based on the value of PRODUCT_INSTALLATION_DIR and RELATIVE_PATH or ABSOLUTE_PATH, as described previously.</td> 
 </tr> 
 <tr> 
 <td style="border:1px solid rgb(187,187,187); margin:10px; padding:10px 8px; color:rgb(42,42,42); vertical-align:top"> START_PATH</td> 
 <td style="border:1px solid rgb(187,187,187); margin:10px; padding:10px 8px; color:rgb(42,42,42); vertical-align:top"> This is the directory from which the wizard was started.</td> 
 </tr> 
 <tr> 
 <td style="border:1px solid rgb(187,187,187); margin:10px; padding:10px 8px; color:rgb(42,42,42); vertical-align:top"> TEMPLATES_PATH</td> 
 <td style="border:1px solid rgb(187,187,187); margin:10px; padding:10px 8px; color:rgb(42,42,42); vertical-align:top"> The directory in which the templates are located. Its default value is&nbsp;&lt;START_PATH&gt;\Templates\&lt;LangID&gt;. A wizard can have templates in more than one language like the MFC Application wizard; in this case the wizard must change the default value in order to use the correct set of templates.</td> 
 </tr> 
 <tr> 
 <td style="border:1px solid rgb(187,187,187); margin:10px; padding:10px 8px; color:rgb(42,42,42); vertical-align:top"> VS_INSTALLATION_DIR</td> 
 <td style="border:1px solid rgb(187,187,187); margin:10px; padding:10px 8px; color:rgb(42,42,42); vertical-align:top"> Visual Studio is installed at this location. It is only defined for Project wizards. Its value is usually&nbsp;&lt;VS Installation Directory&gt;\Common7\IDE\.</td> 
 </tr> 
 <tr> 
 <td style="border:1px solid rgb(187,187,187); margin:10px; padding:10px 8px; color:rgb(42,42,42); vertical-align:top"> WIZARD_TYPE</td> 
 <td style="border:1px solid rgb(187,187,187); margin:10px; padding:10px 8px; color:rgb(42,42,42); vertical-align:top"> This symbol identifies the type of wizard that is being invoked. Its value can be: 
 <ul> 
 <li>Add item wizards {0F90E1D1-4999-11D1-B6D1-00A0C90F2744}.</li> 
 <li>Adding subproject {0F90E1D2-4999-11D1-B6D1-00A0C90F2744}.</li> 
 <li>New project wizards {0F90E1D0-4999-11D1-B6D1-00A0C90F2744}.</li> 
 </ul> </td> 
 </tr> 
 </tbody> 
</table>

### Template Files ###

Template files provide a flexible way for wizards to generate files. The grammar for the templates is very simple and its directives can be found [here][]. The templates.inf file is the master list for all other template files while also being a template itself. Thus, the content of generated files as well as the list of files to generate can both be customized via the template grammar.

The format of templates.inf is as follows:

*  Each line in the file (unless it's a template directive) identifies a template file to be added to the project.
 *  Each line (including the last one in the file) must be terminated by a new-line character.
 *  Filenames in the file are relative to the location of the templates.inf file.
 *  Filenames can be preceded by optional flags. If these flags are present they are separated from each other and from the filename with a pipe ('|') character. The available flags are listed in table 7.

**Table 7. Optional file flags**

## Writing a Custom Wizard ##

Visual C++ 2005 provides an extensibility model with which you can create your own wizards. There are two simple ways of creating a custom wizard. One is to take an existing wizard and modify it to your needs; the other is to use the 'Custom Wizard' wizard to generate a wizard skeleton and start from there.

![Aa730846.invcwiz02(en-US,VS.80).gif][Aa730846.invcwiz02_en-US_VS.80_.gif]

**Figure 2. Custom Wizard**

After clicking on the **Finish** button you will get a project that includes the files listed in Table 8.

**Table 8. Custom Wizard files**

<table style="border-collapse:collapse; padding:0px; width:1097px; border:1px solid rgb(187,187,187)"> 
 <tbody> 
 <tr> 
 <td style="border:1px solid rgb(187,187,187); margin:10px; padding:10px 8px; color:rgb(42,42,42); vertical-align:top"> Wizard information files</td> 
 <td style="border:1px solid rgb(187,187,187); margin:10px; padding:10px 8px; color:rgb(42,42,42); vertical-align:top"> Files used by the&nbsp;New Project&nbsp;dialog to display information about the wizard. These include the wizard information file (.vsz), which tells Visual Studio how to open it; a directory information file (.vsdir), which contains a description of the wizard; and an icon.</td> 
 </tr> 
 <tr> 
 <td style="border:1px solid rgb(187,187,187); margin:10px; padding:10px 8px; color:rgb(42,42,42); vertical-align:top"> User interface files</td> 
 <td style="border:1px solid rgb(187,187,187); margin:10px; padding:10px 8px; color:rgb(42,42,42); vertical-align:top"> HTML pages, images, and cascading style sheets.</td> 
 </tr> 
 <tr> 
 <td style="border:1px solid rgb(187,187,187); margin:10px; padding:10px 8px; color:rgb(42,42,42); vertical-align:top"> Default.js script file</td> 
 <td style="border:1px solid rgb(187,187,187); margin:10px; padding:10px 8px; color:rgb(42,42,42); vertical-align:top"> This JScript file includes the functions used to generate the project.</td> 
 </tr> 
 <tr> 
 <td style="border:1px solid rgb(187,187,187); margin:10px; padding:10px 8px; color:rgb(42,42,42); vertical-align:top"> Templates.inf templates list file</td> 
 <td style="border:1px solid rgb(187,187,187); margin:10px; padding:10px 8px; color:rgb(42,42,42); vertical-align:top"> Lists all the files that the wizard must add to the generated project.</td> 
 </tr> 
 <tr> 
 <td style="border:1px solid rgb(187,187,187); margin:10px; padding:10px 8px; color:rgb(42,42,42); vertical-align:top"> Template files</td> 
 <td style="border:1px solid rgb(187,187,187); margin:10px; padding:10px 8px; color:rgb(42,42,42); vertical-align:top"> Files that the wizard can use to generate a project. By default, there are two text files and a basic Visual C++ project file (.vcproj).</td> 
 </tr> 
 </tbody> 
</table>

Once your wizard skeleton is created (or you have made a copy of an existing wizard to modify) you will likely want to do some of the following tasks:

*  Modify the .vsdir and .vsz files to point to your wizard.
 *  Add or modify the icon associated with your wizard.
 *  Author the HTML pages that make up your wizard.
 *  Create the template files that your wizard will add to the project.
 *  Write the JScript code that performs the actions in your wizard.
 *  Test and debug your wizard.
 *  Localize your wizard to different locales.
 *  Deploy your wizard.

We provide some guidelines and tips for each of these activities in this section.

### Modifying .vsdir and .vsz files ###

The contents of these files were described in detail in the previous sections. Here we include some additional notes.

If you modified an existing wizard, the .vsdir file most likely refers to resources in a binary package that ships with Visual Studio. Make sure that you have created a new line in your own .vsdir file that references your resources. Adding a new line to the existing .vsdir files makes deployment much more difficult.

You must also decide whether to use the RELATIVE\_PATH or the ABSOLUTE\_PATH parameter in the .vsz file to locate your wizard. Each of these options has its own deployment benefits and problems. Note that the default wizard generates a .vsz file with an ABSOLUTE\_PATH directive.

The default wizard puts the .vsz, .vsdir, and icon files into the product install directory in such a manner that your custom wizard shows up in the main Visual C++ tab in the **New Project**dialog. All other generated files are located in your Custom Wizard project directory.

If you decide to delete a custom wizard, you must remove the .vsz, .vsdir, and Icon files from your product install directory, as well, or your **New Project** dialog will be polluted with broken references to deleted wizards.

### Add or Modify Icon Files ###

The icon for a custom wizard is usually located by the .vsz file and has the same name as the .vsz file. You can use any icon editor to edit these files, including Visual Studio's built-in resource editor. Note that the **New Project** dialog has two listing modes, each of which uses a different icon size. Therefore, you should make sure to create two icon resolutions.

### Author HTML Pages ###

Visual Studio has an HTML editor, which supports a design view as well as a source view, and gives you a practical way to edit the visual components of your wizard. Wizards can utilize any number of HTML features and we include a stylesheet, which you can also customize. You can include custom elements in your pages and reference external sites; however, you should keep security in mind. The wizard pages run in a custom zone of Internet Explorer. This zone allows execution of JScript code and access to safe-for-scripting ActiveX controls, but it disallows many other operations. For example, accessing a non-safe-for-scripting ActiveX control will result in a 'gold bar' showing up on your wizard.

Make sure to chose the right set of symbols and that all required information is saved in the symbol table. It is the only permanent data structure, which is passed to the **OnFinish** function in default.js once the user presses the **Finish **button.

### Creating Template Files ###

Template files are the easiest way of creating New Project and New Item wizards. Make sure that you use the correct set of symbols in them. Take special care of the flags you set on individual files in templates.inf, as they can have implications on localization and project deployment.

### Write JScript Code for Your Wizard ###

This is where the core functionality of the wizard will reside. As a minimum, you will have to write the **OnFinish** method in default.js. If your wizard uses template files, you must also implement the **GetTargetName** method to associate project file names to template file names. However, since the actual project generation is done in Jscript, you can choose to implement your own template file parsing, name generation, and so on.

Scripts in your wizard are executed in two distinct environments: inside Internet Explorer during the UI portion of the wizard, and in a hosted scripting environment after the user clicks the**Finish **button. In both cases common.js is included before your code gets loaded by the wizard engine so all its functionality is available to you.

The wizard engine is a COM object, exposing some utility functions for script code. The way you access this object in the two environments is slightly different. Inside the HTML pages you use the **window.external** object, while inside default.js you use the **wizard** object. So, for example, you can find out a value of a symbol by calling**window.external.FindSymbol("PROJECT\_NAME")** in an HTML page, and **wizard.FindSymbol("PROJECT\_NAME")** in default.js. If you want to write unified code that can be used in both environments, use the following trick:

var oWizard;
          try
          {
             oWizard = wizard;
          }
          catch(e)
          {
             oWizard = window.external;
          }
          oWizard.FindSymbol("PROJECT_NAME")

For a complete list of all the APIs that you can call, you can open the typelib for VSWizard.dll or refer to MSDN documentation on the [VCWizCtl Object Properties, Methods, and Events][VCWizCtl Object Properties_ Methods_ and Events]page in the MSDN library.

#### Error Reporting ####

One of the important facilities provided by the wizard engine is the capability to report errors to the user. The **SetErrorInfo** method in the wizard engine is used to set the error message that you want to be displayed upon exiting the wizard. This method takes an **Error** object as the parameter. Another method in the wizard engine, called **ReportError**, immediately displays the error message and returns control to the wizard code. **ReportError** takes a string as the parameter, but it can also be called with no parameter to emit the error message already set by **SetErrorInfo**.

#### The DTE Property ####

The **DTE **property of the **wizard engine** object gives you access to all the rich object models inside Visual Studio. You can find detailed documentation about each of these object models on the [Visual C++ Reference][Visual C_ Reference] page in the MSDN library.

Two of the available object models are of particular interest when designing Visual C++ wizards:

#### The Project Model ####

The Project Model is part of Visual Studio's object model. It lets you programmatically interact with a project, change its properties (like compiler options), and add or remove project items, such as code or resource files. The main interfaces are listed in table 9.

**Table 9. Project Model interfaces**

The project creation wizards get a reference to the created project when they call the **CreateProject** method. All other wizards get a reference to the Project instance in question as an argument to the **OnFinish** function declared in the default.js file.

For a complete explanation of the Project Model refer to the [Visual C++ Project Model][Visual C_ Project Model] topics in MSDN.

#### The Code Model ####

With the wizard control functions it is easy to create new projects and add new files to existing projects. However, sometimes you need to add code to existing files or modify code that already exists. In order to do this, your wizard must have a way to understand code. In these situations, you can make use of the Code Model. It parses the code and provides an easy way for your wizard to understand and modify existing code. It is an object model for code files, consisting of different objects and collections that provide information on language constructs that exist within a project. The properties and methods on these objects allow you to create new code elements or modify existing ones. The main interfaces are listed in table 10.

**Table 10. Code Model interfaces**

<table style="border-collapse:collapse; padding:0px; width:1097px; border:1px solid rgb(187,187,187)"> 
 <tbody> 
 <tr> 
 <td style="border:1px solid rgb(187,187,187); margin:10px; padding:10px 8px; color:rgb(42,42,42); vertical-align:top"> CodeModel</td> 
 <td style="border:1px solid rgb(187,187,187); margin:10px; padding:10px 8px; color:rgb(42,42,42); vertical-align:top"> This object is the root of a project's code tree. Its&nbsp;CodeElements&nbsp;property is a collection that contains all the code elements (such as classes, functions, variables, and so on) that are declared at the project's global namespace level.</td> 
 </tr> 
 <tr> 
 <td style="border:1px solid rgb(187,187,187); margin:10px; padding:10px 8px; color:rgb(42,42,42); vertical-align:top"> FileCodeModel</td> 
 <td style="border:1px solid rgb(187,187,187); margin:10px; padding:10px 8px; color:rgb(42,42,42); vertical-align:top"> This object is very similar to&nbsp;CodeModel&nbsp;but it represents the root of a file's code tree (as opposed to that of the entire project).</td> 
 </tr> 
 <tr> 
 <td style="border:1px solid rgb(187,187,187); margin:10px; padding:10px 8px; color:rgb(42,42,42); vertical-align:top"> CodeElement</td> 
 <td style="border:1px solid rgb(187,187,187); margin:10px; padding:10px 8px; color:rgb(42,42,42); vertical-align:top"> This interface represents one particular code element declared in a project file. Each code element can have nested children; for example, a namespace can contain nested classes or even nested namespaces. Its&nbsp;Children&nbsp;property provides a collection of all the nested children (note that each child can have children of its own that will not show in the Children collection of the common ancestor).</td> 
 </tr> 
 <tr> 
 <td style="border:1px solid rgb(187,187,187); margin:10px; padding:10px 8px; color:rgb(42,42,42); vertical-align:top"> Language construct interfaces</td> 
 <td style="border:1px solid rgb(187,187,187); margin:10px; padding:10px 8px; color:rgb(42,42,42); vertical-align:top"> This is a group of interfaces that derive from&nbsp;CodeElement&nbsp;and provide functionality specific to each code element type. Examples of these interfaces are&nbsp;CodeClass,CodeStruct,&nbsp;CodeVariable, and so on.</td> 
 </tr> 
 <tr> 
 <td style="border:1px solid rgb(187,187,187); margin:10px; padding:10px 8px; color:rgb(42,42,42); vertical-align:top"> C++-specific interfaces</td> 
 <td style="border:1px solid rgb(187,187,187); margin:10px; padding:10px 8px; color:rgb(42,42,42); vertical-align:top"> This is a group of objects, providing access to language-specific aspects of various elements in the source-code. Examples of these interfaces are&nbsp;VCCodeClass,VCCodeFunction, and so on.</td> 
 </tr> 
 </tbody> 
</table>

For an introduction to the Code Model refer to the MSDN topic [Discovering Code with the Code Model][].

For a reference of object, interfaces, methods and properties in this rich object-model, refer to the MSDN topic [Visual C++ Extensibility Object Model][Visual C_ Extensibility Object Model].

### Debugging ###

To debug the script in the wizard's HTML and script files, you must first enable script debugging. This can be done by the following steps:

1.  In Internet Explorer, click the **Tools** menu and choose **Internet Options**.
2.  Click the **Advanced** tab.
3.  Under the Browsing category, clear the **Disable Script Debugging** checkbox.

Once you do this, you can attach another Visual Studio process to your current Visual Studio process as a script debugger. You can set breakpoints in your script blocks within your HTML files and default.js and other script files.

In some cases the chain of events can be rather confusing, so knowing when to attach and where to put a breakpoint can be challenging. In those cases putting some pop-up dialogs into your script code can help. You can use the **ReportError** method of the **wizard engine** object to add pop-ups to your code:

var oWizard;
          try
          {
             oWizard = wizard;
          }
          catch(e)
          {
             oWizard = window.external;
          }
          oWizard.ReportError("Break Me!")

Once your pop-up appears, you can attach a debugger, set a break-point and dismiss the dialog.

### Localizing ###

The default wizard templates were designed to make localization simple and straightforward. For this reason, all the wizards have templates, scripts, and HTML files in their respective locale directories. It is thus relatively easy to take the English version of the files in the 1033 subdirectory and provide localized versions in the appropriate locale directory. Visual Studio will automatically access the files under the right locale subdirectory if they exist. If they do not exist, the system reads files under the directory associated to the locale identified by the FALLBACK\_LCID symbol. For example, you may ship English (1033) and German (1031) versions of your wizard, and mark your FALLBACK\_LCID to be 1033. When a user in a locale other than English and German starts up the wizard, the engine will detect that it is missing the localized files for that locale and bring up the wizard in English.

### Deployment ###

Deploying your wizards to customer machines is usually no more complicated than copying the right set of files to the right locations. You will need your .vsdir and .vsz files, along with the icon for the wizard, put in the right product folder. You will also have to copy all the HTML, JScript, template, and other files that make up your wizard to the target machine. You can figure out the right location for the .vsdir, .vsz, and icon files by looking at the registry key values mentioned in [table 2][]. If you use the RELATIVE\_PATH parameter to locate your wizard files, then these registry values can help you determine the target location for the wizard files. On the other hand, the ABSOLUTE\_PATH parameter works consistently on all machines. However, if you cannot put the wizard files at the exact same location on all machines, you may have to re-write your .vsz file during deployment.

## Conclusion ##

At first glance, the Visual Studio wizard architecture may seem too complex. Indeed, wizards are composed of JScript, HTML, templates, images, and even some custom files. This apparent complexity is an artifact of our desire to make the wizard engine as flexible as possible. On the one hand, the wizards we ship can be fully customized simply by modifying their files according to the guidelines in this document. On the other hand, creating new wizards is quite straightforward using the custom wizard generator. Furthermore, shipping international products that include custom wizards is much easier thanks to our support for localization. Thus, with this document as a guide, working with wizards in Visual Studio should be highly rewarding.

**About the authors**

**Shankar Vaidyanathan** is the development lead for the Visual C++ IDE. Amongst other things, he was instrumental in shipping .Net designers and IntelliSense & Design-Time browser (reference information) over the last several product releases. He has filed for a dozen patents; half of them have already been awarded and the remaining are under review. He has trained his vocal chords for classical music, but he has no hopes of quitting his day job for that.

**Gabriel Esparza-Romero** is originally from sunny Oaxaca Mexico. After attending college at ITESM he joined Microsoft. In the last 7 years he has held different positions in the C++ and C\# QA teams. He is currently working on the next version of the C\# editor.

**Andras Tantos** is a software developer in the Visual C++ IDE team. He has spent 4 years at Microsoft and is currently responsible for the improvements in the wizards infrastructure and the CodeModel. He holds an MSEE degree from the Technical University of Budapest.

**Boris Jabes** is a program manager on the Visual C++ IDE team. He is responsible for features spanning areas such as Intellisense, Browsing and the editor. He holds degrees from the University of Waterloo and Carnegie Mellon University.

[http_msdn.microsoft.com_en-us_library_aa730846_v_vs.80_.aspx]: http://msdn.microsoft.com/en-us/library/aa730846%28v=vs.80%29.aspx
[Introduction]: http://msdn.microsoft.com/en-us/library/aa730846%28v=vs.80%29.aspx#invcwiz_topic1
[Walkthrough of Wizard Execution]: http://msdn.microsoft.com/en-us/library/aa730846%28v=vs.80%29.aspx#invcwiz_topic2
[Delving into the Wizard Architecture]: http://msdn.microsoft.com/en-us/library/aa730846%28v=vs.80%29.aspx#invcwiz_topic3
[Writing a Custom Wizard]: http://msdn.microsoft.com/en-us/library/aa730846%28v=vs.80%29.aspx#invcwiz_topic4
[Conclusion]: http://msdn.microsoft.com/en-us/library/aa730846%28v=vs.80%29.aspx#invcwiz_topic5
[Aa730846.invcwiz01_en-US_VS.80_.gif]: http://i.msdn.microsoft.com/dynimg/IC17099.gif
[VCWizCtl Object Properties_ Methods_ and Events]: http://msdn2.microsoft.com/en-us/library/microsoft.visualstudio.vswizard.vcwizctl%28VS.80%29.aspx
[Table 6]: http://msdn.microsoft.com/en-us/library/aa730846%28v=vs.80%29.aspx#invcwiz_tab6
[Template Files]: http://msdn.microsoft.com/en-us/library/aa730846%28v=vs.80%29.aspx#invcwiz_temfile
[table 2]: http://msdn.microsoft.com/en-us/library/aa730846%28v=vs.80%29.aspx#invcwiz_table2
[VSDir Files]: http://msdn.microsoft.com/en-us/library/aa291929%28v=vs.80%29.aspx
[here]: http://msdn2.microsoft.com/en-us/library/bf952e4s%28VS.80%29.aspx
[Aa730846.invcwiz02_en-US_VS.80_.gif]: http://i.msdn.microsoft.com/dynimg/IC140724.gif
[Visual C_ Reference]: http://msdn2.microsoft.com/en-us/library/174179de%28VS.80%29.aspx
[Visual C_ Project Model]: http://msdn2.microsoft.com/en-us/library/2eydyk57%28VS.80%29.aspx
[Discovering Code with the Code Model]: http://msdn.microsoft.com/en-us/library/aa293004%28v=vs.80%29.aspx
[Visual C_ Extensibility Object Model]: http://msdn2.microsoft.com/en-us/library/c2a19k26%28VS.80%29.aspx
[Microsoft Corporation. All rights reserved.]: http://msdn.microsoft.com/en-us/library/ms369863%28v=vs.80%29.aspx