Walkthru:Creating a Wizard 

Glossary Item Box

Walkthrough: Creating a Wizard

Visual Studio wizards allow you to build a custom UI that walks a user through one or more steps for creating something or accomplishing a task. Wizards are perfect for two main, often repetitive, programming tasks: creating a new project and adding new items to a project.

The following walkthrough shows you how to create, register and use a one-step wizard that prompts you for configuration information when adding a new app.config file to a Windows Forms project.

1.  In Visual Studio 2005 create a new C# Class Library project named "WizardWalkthrough".

2.  In the Solution Explorer, change the file name of Class1.cs to "AppConfigWizard.cs". If you are prompted to change the class name, select Yes. 

Wizards run as COM objects, which require registration. To register the wizard, all you need to do is declare the class with a GuidAttribute attribute. Then, when you build the project, Visual Studio automatically registers the compiled DLL.

3.  In the Solution Explorer, right-click WizardWalkthrough and select Properties. In the Application tab, click Assembly Information. Check Make assembly COM visible, then click OK. Click the Build tab and then check Register for COM interop. Close the Properties window.

4.  At the top of AppConfiWizard.cs add a reference ("using" statement) to the System.Runtime.InteropServices namespace.

5.  Above the class declaration add the following attribute:

[Guid("")]

6.  Select the Tools | Create GUID menu command. In the Create GUID dialog select Registry Format. Click Copy and then click Exit.

7.  Paste the copied GUID value between the double quotes in the GuidAttribute declaration. Delete the braces that wrap the value.

Creating a wizard requires you to implement the IDTWizard interface found in the EnvDTE assembly.

8.  In the Solution Explorer , right-click References and asdd a reference to the EnvDTE assembly.

9. Modify the AppConfigWizard class to implement the IDTWizard interface, which contains only one member, the Execute method. Your code should look like the following, though your GUID will be different:

  using System;
using System.Collections.Generic;
using System.Text;
using System.Runtime.InteropServices;

namespace WizardWalkthrough
{
	[GuidAttribute("066700A6-4BD9-43fd-8839-E094E34E6773")]
	public class AppConfigWizard:EnvDTE.IDTWizard
	{
		void EnvDTE.IDTWizard.Execute(
			object Application, 
			int hwndOwner, 
			ref object[] ContextParams,
			ref object[] CustomParams,
			ref EnvDTE.wizardResult retval)
		{
			// Add wizard functionality.
		}
	}
}

You are now ready to create a UI for your wizard. This will consist of a Windows Form that allows a user to specify configuration elements when adding an app.config file to a Windows Forms project.

10.  In the Solution Explorer right-click WizardWalkthrough, select Add | New Item and add a new Windows Form to the project with the name "AppConfigWizardUI.cs".

11.  Add controls to make your Form look like the following diagram. Name the CheckBox control "checkBoxAddTraceElement". Name the Button "buttonAddConfigFile". Name the top TextBox "textBoxListenerName" and the bottom TextBox "textBoxLogFilePath". Set the Enabled property to False for both TextBox and Label controls.

12.  Double-click the CheckBox control to create a CheckedChanged event handler. To this handler add the following code:

  if (checkBoxAddTraceElement.Checked)
{
	label1.Enabled = true;
	label2.Enabled = true;
	textBoxListenerName.Enabled = true;
	textBoxLogFilePath.Enabled = true;
}
else
{
	label1.Enabled = false;
	label2.Enabled = false;
	textBoxListenerName.Enabled = false;
	textBoxLogFilePath.Enabled = false;
}

The wizard UI needs access to the running IDE instance exposed by the EnvDTE.DTE object. (DTE stands for Development Tools Extensibility). To gain access you will now add a public property that will be set by the wizard class when the Form is instantiated.

13.  At the top of AppConfigWizardUI.cs add a reference ("using" statement) to the EnvDTE namespace. Just inside the class declaration add the following code to create a property of type EnvDTE._DTE, which represents the DTE interface:

  private _DTE dte;
public EnvDTE._DTE MyDTE
{
	set
	{
		dte = value;
	}
}

14.  Switch to the Design view and double-click the Add Config File button. To the Click event handler add the following code:

Array projectsActive = (Array)dte.ActiveSolutionProjects;
Project projectActive = (Project)projectsActive.GetValue(0);
string docConfigPath = 
   projectActive.FullName.Replace(projectActive.Name + ".csproj",   
   "app.config");

System.Xml.XmlTextWriter writer = new System.Xml.XmlTextWriter(docConfigPath, null);
writer.Formatting = System.Xml.Formatting.Indented;
writer.WriteStartDocument();
writer.WriteStartElement("configuration");
writer.WriteStartElement("system.diagnostics");
writer.WriteStartElement("trace");
writer.WriteAttributeString("autoflush", "true");
writer.WriteAttributeString("indentsize", "0");
writer.WriteStartElement("listeners");
writer.WriteStartElement("add");
writer.WriteAttributeString("name", 
   this.textBoxListenerName.Text);
writer.WriteAttributeString("type", 
   "System.Diagnostics.TextWriterTraceListener, system" +   
   "version=1.0.3300.0, Culture=neutral," + 
   "PublicKeyToken=b77a5c561934e089");
writer.WriteAttributeString("initializeData", 
   this.textBoxLogFilePath.Text);
writer.WriteEndElement();
writer.WriteEndElement();
writer.WriteEndElement();
writer.WriteEndElement();
writer.WriteFullEndElement();
writer.Close();

projectActive.ProjectItems.AddFromFile(docConfigPath);
this.Close();

The bulk of this code consists of straightforward XmlTextWriter method calls to create the app.config file. The opening and closing lines are more relevant to this walkthrough. The first few lines show you how to access the active project—i.e., the project that the user has currently selected and to which they are adding a new item. The ActiveSolutionProjects property is of type Object, but you must cast it to an Array in order to use GetValue in the next line to cast the object to an EnvDTE.Project type. You use this both to determine the path to the project (for writing the XML document) and to call the ProjectItems.AddFromFile method at the end.

15.  In the AppConfigWizard class, in the Execute method, add the following code to instantiate the wizard UI form, set its MyDTE property and show it as a modal dialog:

AppConfigWizardUI formWizardUI = new AppConfigWizardUI();
formWizardUI.MyDTE = (EnvDTE._DTE)Application;
formWizardUI.ShowDialog();

You are now ready to compile your wizard into a DLL. The build process will also register the DLL as a COM component.

16.  Select the Build | Build Solution menu command (or press CTRL+SHIFT+B ).

The final step is to register the wizard as a Visual Studio template. You do this by creating a .vsz file, which the IDE uses to recognize and run wizards.

17.  Open Windows Explorer and navigate to the location of the Visual Studio C# project item wizards. The path for a default installation is C:\Program Files\Microsoft Visual Studio 8\VC#\CSharpProjectItems .

18.  In the CSharpProjectItems folder, right-click and select New | Text Document. Open New Text Document.txt and add the following two lines, which specify the version number for the template file format and the GUID or full name of the wizard assembly:

VSWIZARD 7.0
Wizard=WizardWalkthrough.AppConfigWizard

You can also assign the wizard class's GUID value from the GuidAttribute construction.

19.  Save the file as App.Config Wizard.vsz (make sure that the file does NOT save as type .txt). Close the file and then delete New Text Document.txt.

20.  Start another instance of Visual Studio 2005 . Create a new C# Windows Application project. In the Solution Explorer right-click the project and select Add | New Item.

21.  In the Add New Item dialog select App.Config Wizard, and then click Add.

22.  In the App Config Wizard check Provide<Trace> Details. For Listener Name enter "myListener" and for Log File Path enter "c:\logs\myListener.log". Click Add Config File.

23.  In the Solution Explorer double-click app.config.

In this walkthrough you learned how to build, register and use a Visual Studio "Add New Item" wizard that has a Windows Forms UI. You saw that this involves creating a custom class that implements one method in the IDTWizard interface; declaring the class with an instance of GuidAttribute, and then setting two project-level properties for COM exposure. You also learned that a VSZ file must be created and placed in the appropriate subfolder of your Visual Studio installation. With this basic understanding you are now ready to build your own, more robust wizards. For example, you could easily create an app.config wizard that has numerous configuration sections instead of only the trace section, as you saw here.