How-To Create an Initialization Wizard
Applies To: Windows 10, Windows 7, Windows 8, Windows 8.1, Windows Server 2008, Windows Server 2008 R2, Windows Server 2012, Windows Server 2012 R2, Windows Server Technical Preview, Windows Vista
A wizard is a special type of PropertySheet that provides a simple and powerful way to guide users through complex procedures. This sample demonstrates an initialization wizard that pops up during the process of adding the snap-in to the MMC console and requests a name for the snap-in. Once the name is provided, the snap-in assumes that name.
Create InitializationWizardSnapIn class (file InitializationWizardSnapIn.cs)
Create an InitializationWizardSnapIn class. This step is similar to the step for creating a snap-in in the previous samples.
using System; using System.ComponentModel; using System.Configuration; using System.Text; using System.Windows.Forms; using Microsoft.ManagementConsole; namespace Microsoft.ManagementConsole.Samples { /// <summary> /// Allows the .Net framework to install the assembly. /// </summary> [RunInstaller(true)] public class InstallUtilSupport : SnapInInstaller { } /// <summary> /// Provides the main entry point for the creation of a snap-in. /// </summary> [SnapInSettings("{2DACA4C5-ADB7-4f98-ADB7-C965D81EC9B3}", DisplayName = "- Initilization Wizard SnapIn", Description = "Sample - Shows Wizard during Add to Console")] public class InitializationWizardSnapIn : SnapIn { /// <summary> /// Constructor. /// </summary> public InitializationWizardSnapIn() { this.RootNode = new ScopeNode(); this.RootNode.DisplayName = "Unknown"; this.IsModified = true; // tells mmc to save custom data } ... } //class } // namespaceThis method overrides the OnShowInitializationWizard method. It shows the initialization wizard when the snap-in is added to console. When true is returned, the snap-in continues to load. If a false value is returned, MMC cancels the loading of the snap-in.
/// <summary> /// Show the initialization wizard when the snap-in is added to console. /// </summary> /// <returns></returns> protected override bool OnShowInitializationWizard() { // Show a modal dialog to get the snap-in name. InitializationWizard initializationWizard = new InitializationWizard(); bool result = (this.Console.ShowDialog(initializationWizard) == DialogResult.OK); if (result) { this.RootNode.DisplayName = initializationWizard.SelectedSnapInName; } return result; }This method overrides OnLoadCustomData. It is used to load in any saved data. The status parameter is the asynchronous status for updating the console. The persistenceData parameter is the binary data that is stored in the console file.
/// <summary> /// Load any unsaved data. /// </summary> /// <param name="status"></param> /// <param name="persistenceData"></param> protected override void OnLoadCustomData(AsyncStatus status, byte[] persistenceData) { // If the na,e is saved, then set the display name of the snap-in. if (string.IsNullOrEmpty(Encoding.Unicode.GetString(persistenceData))) { this.RootNode.DisplayName = "Unknown"; } else { this.RootNode.DisplayName = Encoding.Unicode.GetString(persistenceData); } }This method overrides OnSaveCustomData. It saves the data if the snap-in name was modified. It returns binary data to be stored in the console file. This method allows a snap-in to pass a serializable object to the method so that its contents may be persisted into a binary section in the console file.
/// <summary> /// If the snap-in has been modified, then save the data. /// </summary> /// <param name="status"></param> /// <returns></returns> protected override byte[] OnSaveCustomData(SyncStatus status) { return Encoding.Unicode.GetBytes(this.RootNode.DisplayName); }Here is the complete code for creating the InitializationWizardSnapIn class.
using System; using System.ComponentModel; using System.Configuration; using System.Text; using System.Windows.Forms; using Microsoft.ManagementConsole; namespace Microsoft.ManagementConsole.Samples { /// <summary> /// Allows the .Net framework to install the assembly. /// </summary> [RunInstaller(true)] public class InstallUtilSupport : SnapInInstaller { } /// <summary> /// Provides the main entry point for the creation of a snap-in. /// </summary> [SnapInSettings("{2DACA4C5-ADB7-4f98-ADB7-C965D81EC9B3}", DisplayName = "- Initilization Wizard SnapIn", Description = "Sample - Shows Wizard during Add to Console")] public class InitializationWizardSnapIn : SnapIn { /// <summary> /// Constructor. /// </summary> public InitializationWizardSnapIn() { this.RootNode = new ScopeNode(); this.RootNode.DisplayName = "Unknown"; this.IsModified = true; // tells mmc to save custom data } /// <summary> /// Show the initialization wizard when the snap-in is added to console. /// </summary> /// <returns></returns> protected override bool OnShowInitializationWizard() { // Show a modal dialog to get the snap-in name. InitializationWizard initializationWizard = new InitializationWizard(); bool result = (this.Console.ShowDialog(initializationWizard) == DialogResult.OK); if (result) { this.RootNode.DisplayName = initializationWizard.SelectedSnapInName; } return result; } /// <summary> /// Load any unsaved data. /// </summary> /// <param name="status"></param> /// <param name="persistenceData"></param> protected override void OnLoadCustomData(AsyncStatus status, byte[] persistenceData) { // If the na,e is saved, then set the display name of the snap-in. if (string.IsNullOrEmpty(Encoding.Unicode.GetString(persistenceData))) { this.RootNode.DisplayName = "Unknown"; } else { this.RootNode.DisplayName = Encoding.Unicode.GetString(persistenceData); } } /// <summary> /// If the snap-in has been modified, then save the data. /// </summary> /// <param name="status"></param> /// <returns></returns> protected override byte[] OnSaveCustomData(SyncStatus status) { return Encoding.Unicode.GetBytes(this.RootNode.DisplayName); } } //class } // namespace
Create the initialization wizard (file InitializationWizard.cs)
This creates the wizard class. It is essentially a form that requests a name for the snap-in.
using System; using System.Windows.Forms; namespace Microsoft.ManagementConsole.Samples { /// <summary> /// Create the form that gets the name of the snap-in. /// </summary> public partial class InitializationWizard : Form { /// <summary> /// Constructor. /// </summary> public InitializationWizard() { InitializeComponent(); this.SelectedSnapInName = "Unknown"; } ... //Define a property called SelectedSnapInName and get and set methods for it. /// <summary> /// Gets the entered name. /// </summary> public string SelectedSnapInName { get { return SnapInName.Text; } set { SnapInName.Text = value; } } } // form } // namespaceAdd a method that handles the click of the Continue button.
/// <summary> /// Handles a click of the Continue button. /// </summary> /// <param name="sender"></param> /// <param name="e"></param> private void Continue_Click(object sender, EventArgs e) { this.DialogResult = DialogResult.OK; }Here is the complete code for creating the InitializationWizard class.
using System; using System.Windows.Forms; namespace Microsoft.ManagementConsole.Samples { /// <summary> /// Create the form that gets the name of the snap-in. /// </summary> public partial class InitializationWizard : Form { /// <summary> /// Constructor. /// </summary> public InitializationWizard() { InitializeComponent(); this.SelectedSnapInName = "Unknown"; } /// <summary> /// Handles a click of the Continue button. /// </summary> /// <param name="sender"></param> /// <param name="e"></param> private void Continue_Click(object sender, EventArgs e) { this.DialogResult = DialogResult.OK; } //Define a property called SelectedSnapInName and get and set methods for it. /// <summary> /// Gets the entered name. /// </summary> public string SelectedSnapInName { get { return SnapInName.Text; } set { SnapInName.Text = value; } } } // form } // namespace
Initialization wizard designer (file InitializationWizard.Designer.cs)
For reference, here is part of the designer code for the initialization wizard.
namespace Microsoft.ManagementConsole.Samples { partial class InitializationWizard { private System.ComponentModel.IContainer components = null; /// <summary> /// Clean up any resources being used. /// </summary> /// <param name="disposing">true if managed resources should be disposed; otherwise, false.</param> protected override void Dispose(bool disposing) { if (disposing && (components != null)) { components.Dispose(); } base.Dispose(disposing); } ... private System.Windows.Forms.Label ValueText; private System.Windows.Forms.Label ImplementationNote; private System.Windows.Forms.TextBox SnapInName; private System.Windows.Forms.Label NamePrompt; private System.Windows.Forms.Button Ok; private System.Windows.Forms.Panel panel1; private System.Windows.Forms.Button Cancel; } }All the code for this sample is available in the <MMC 3.0 Samples>\PropertySheetSample directory.
Steps to create, install, and run the snap-in
To install this snap-in, run the .NET Framework InstallUtil.exe program using the following command-line command: InstallUtil.exe InitializationWizardSample.dll. Note that if the Microsoft.ManagementConsole dll is not in the GAC, the Microsoft.ManagementConsole.dll and the InitializationWizardSample.dll must be in the same directory. If you need to uninstall the snap-in later, run the previous InstallUtil.exe command with the /uninstall switch.
The InstallUtil.exe command attempts to install your snap-in using the SnapInSettingsAttribute. The utility creates a file called InstallUtil.InstallLog to show the success or failure of the install and all the actions that were taken.
InstallUtil.exe populates the registry entries for the given snap-in under the HKLM/Software/Microsoft/MMC/SnapIns key.
After the snap-in is installed, the snap-in is visible to MMC and can be added to the MMC Console using the Add/Remove Dialog. To test this snap-in, run MMC 3.0 (mmc.exe) and use the Add/Remove Snap-in menu. The Initialization Wizard Sample displays in the dialog and can be loaded in the MMC console.