| Wizards are applications that help users perform some task. Generally the task represented by a wizard requires a sequence of specific operations; the point of the wizard is to alleviate tedium or simplify a multistep task into a linear sequence in which all responses yield a functional result. From experience you probably know that Microsoft implements wizards as a sequence of dialog boxes with a graphic, some text providing instruction, and a simple input field or multiple choice selection. These wizards appear to be an integrated part of the application that uses them. Creating wizards in Visual Basic .NETand for VS .NETis easier than creating an add-in. Ironically, there is no wizard that creates wizards. The general steps for creating a wizard for VS .NET are as follows : -
Create a Class Library project. -
Implement the IDTWizard interface and the one method defined by that interface, Execute. When the wizard is invoked, the Execute method is called. -
Implement the wizard behavior, usually a sequence of dialog boxes and an end result. -
Add a reference to the EnvDTE library. -
Compile and register the wizard using Regasm.exe. -
Create a text file with the same name as the wizard and a .vsz extension. For example, MyWizard.Dll needs a text file MyWizard.vsz. (We'll talk more about what is in the text file in a moment.) -
Copy the text file in a folder depending on how you want it invoked. For instance, if you want the wizard to be available when a user selects File, Add New Item in a VB project, copy the .vsz file to the directory containing the Add New Item elements; the default location for the example is C:\ Program Files\ Microsoft Visual Studio.NET\ Vb7\ VBProjectItems\ Local Project Items\. As you can see, the number of steps is roughly equivalent to the number of steps for add-ins, but the actual amount of work is much less. The basic technique is to create a class library that implements IDTWizard, compile the library, and register it. Essentially, you implement one method. (Of course, there is all of the work the wizard will perform, too.) Note Even if you have implemented interfaces in VB6, the syntax has changed between VB6 and VB .NET. You can skip ahead to Chapter 7, "Creating Classes," to learn more about interfaces and then return to this section, or take everything on faith for now.
The code in Listing 4.11 demonstrates a wizard that pops up a message box. Listing 4.11 A wizard that displays a message box provides a good template for creating wizards in general. 1: Imports EnvDTE 2: 3: Public Class Class1 4: Implements IDTWizard 5: 6: Public Sub Execute(ByVal Application As Object, _ 7: ByVal hwndOwner As Integer, _ 8: ByRef ContextParams() As Object, _ 9: ByRef CustomParams() As Object, _ 10: ByRef RetVal As wizardResult) Implements EnvDTE.IDTWizard.Execute 11: 12: MsgBox("Hello World!") 13: RetVal = wizardResult.wizardResultCancel 14: 15: End Sub 16: 17: End Class The Execute method gets several parameters. Application is a reference to the environment the wizard is running in. hwndOwner is the handle of the parent application. ContextParams contains information indicating the context in which the wizard was started; for example, File, Add New Items versus File, New Project. CustomParams are values you can pass to the wizard via the .vsz file in the form of Param=Value statements. RetVal is an enumerated value indicating whether the wizard succeeded or failed. Creating the Wizard Launching File A wizard launching file by convention has the same name as its associated wizard and .vsz extension. The wizard launching file is a simplified file similar to an .ini file, used to pass information to an application; in this instance a class library. The basic format of the .vsz file is a text file with no sections and name and value pairs. For our sample wizard, all we need is a text file containing the following: VSWIZARD 7.0 Wizard=Wizard1.Class1 Param=<Nothing> If you need to pass parameters, pass them in the form Param= value as demonstrated in the sample file. Having written the wizard launching file, copy it to the appropriate directories. As previously mentioned, copy the .vsz file to C:\ Program Files\ Microsoft Visual Studio .NET\ Vb7\ VBProjectItems\ Local Project Items\ to make the wizard available from the File, Add New Item submenu. You can test wizards using macros to launch the wizard. I will demonstrate this technique after we register the wizard. Registering the Wizard Class Library Wizards are basically add-ins. Consequently, you use the same process to register wizards as you did for add-ins earlier in the chapter. To register a wizard, type the full path to the regasm.exe application, the full path to your wizard, and make sure that you use the / codebase switch or the Add-Ins Manager will not be able to find your add-in. Assuming we have the same version of .NET, the following code will register a wizard named mywizard.dll that exists in the current directory. C:\ WINNT\ Microsoft.NET\ Framework\ v1.0.3215\ Regasm.exe mywizard.dll /codebase To unregister the wizard use the /unregister switch with regasm.exe. C:\ WINNT\ Microsoft.NET\ Framework\ v1.0.3215\ Regasm.exe myaddin.dll /unregister Testing the Wizard The wizard is created and registered. The wizard launch file has been copied to the directories that contain other templates. You are now ready to test the wizard. There are two ways you can quickly test the wizard. You can select File, Add New Item (or select the operation based on where you placed the launch file), or you can use a macro to launch the wizard. Listing 4.12 demonstrates a macro that will exercise the wizard. Listing 4.12 Use the Development Tools Environment (DTE) object and a macro to test your wizard 1: Const Path As String = _ 2: "C:\ Program Files\ Microsoft Visual " & _ 3: "Studio .NET\ Vb7\ VBProjectItems\ Local " & _ 4: "Project Items\ Wizard1.vsz" 5: 6: Public Sub RunWizard() 7: Dim Guid As New _ 8: System.Guid("{164B10B9-B200-11D0-8C61-00A0C91E29D5} ") 9: Dim ContextParams(1) As Object 10: ContextParams(0) = Guid 11: ContextParams(1) = Nothing 12: MsgBox("Launching") 13: DTE.LaunchWizard(Path, ContextParams) 14: End Sub The macro RunWizard creates a new GUID, using the GUID constructor and the globally unique identifier that indicates the template repository. (This information was taken from the registry, but doesn't seem to be a very robust way to write code.) The path to the wizard launch file and the array of objects, named ContextParams, are passed to the wizard. | 
