Defining a Wizard

Retired Content
This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

A wizard is defined in the Guidance Package configuration file. A wizard consists of a sequence of pages. The sequence of pages consists of a sequence of fields. Each field corresponds to a recipe argument; this recipe argument is also defined in the Guidance Package configuration file. The value collected in a field is assigned to the corresponding argument by Recipe Framework. The following XML code example shows arguments being defined in a recipe.

<Arguments>
  <Argument Name="CurrentProject" Type="EnvDTE.Project, EnvDTE, Version=8.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a">
    <ValueProvider Type="Microsoft.Practices.RecipeFramework.Library.ValueProviders.FirstSelectedProject, Microsoft.Practices.RecipeFramework.Library" />
  </Argument>
  <Argument Name="ClassName">
    <Converter Type="Microsoft.Practices.RecipeFramework.Library.Converters.CodeIdentifierStringConverter, Microsoft.Practices.RecipeFramework.Library"/>
  </Argument>
  <Argument Name="TargetFile">
    <ValueProvider Type="Evaluator"
    Expression="$(ClassName).cs">
    <MonitorArgument Name="ClassName" />
    </ValueProvider>
  </Argument>
  <Argument Name="TargetNamespace">
    <Converter Type="Microsoft.Practices.RecipeFramework.Library.Converters.NamespaceStringConverter, Microsoft.Practices.RecipeFramework.Library"/>
    <ValueProvider Type="Evaluator"
    Expression="$(CurrentProject.Properties.Item('DefaultNamespace').Value)" />
  </Argument>
  <Argument Name="HelloMessage">
  <Converter Type="PackageNamespace.Converters.HelloWorldConverter, PackageName" />
  </Argument>
</Arguments>

If an argument has a value provider defined for it, the value provider is used to retrieve an initial value for the argument. If the argument is also associated with a field in a wizard, the value gathered by the provider is displayed in the wizard. The <GatheringServiceData> element of the Guidance Package configuration file is used to define a wizard. It contains details of the pages of the wizard and the fields present on those pages, as shown in the following example.

<GatheringServiceData>
  <Wizard xmlns="https://schemas.microsoft.com/pag/gax-wizards" SchemaVersion="1.0" Help="https://localhost:8080/MyRecipe">>
    <Pages>
      <Page>
        <Title>Hello World</Title>
        <Fields>
          <Field ValueName="ClassName" Label="Class Name" />
          <Field ValueName="TargetNamespace" Label="Namespace" />
          <Field ValueName="HelloMessage" Label="Message" />
        </Fields>
      </Page>
    </Pages>
  </Wizard>
</GatheringServiceData>

The precise behavior of the wizard will depend on both argument declaration and the wizard definition. For example, a wizard will contain required fields if the corresponding argument is declared as required. One field may also change in response to change in another field if a value provider for one argument is used to monitor the changes in another argument. In the preceding code example, the argument TargetFile monitors changes in the argument ClassName. Every time the name of the class changes, the name of the file is re-evaluated to make it the name of the class followed by the string ".cs". If the target file name was shown in the wizard, this would have an effect on the wizard behavior; whenever the user changed the filed named ClassName, the value of the field with the file name would change accordingly. Another example is the argument Iterations. It is defined as an integer. The InvalidValueMessage, defined in the <GatheringServiceData> element, will display if the argument is not entered as an integer.

If the text in a label is too much to fit on a wizard page, the text will not all be displayed. However, you can specify a height and width property for each page. If the height and width are defined differently for each page, the Wizard Framework displays the entire wizard using the largest height and width defined.

The Help attribute of the <Wizard> element is used to associate a Help page with the entire wizard. The page can be accessed using the "?" control on the upper-right corner of the wizard window as illustrated in Figure 1.

Figure 1: Help attribute

The Help attribute is optional, and the "?" control will appear only if there is a page associated with the wizard. The type of the attribute is String and the framework does not check whether it contains a well-formed URL.

The page can be referenced by a URL (using the line in the preceding code example), or it can be a Help topic page, as shown in the following code example.

<Wizard xmlns="https://schemas.microsoft.com/pag/gax-wizards" SchemaVersion="1.0" Help=" ms-help://MS.VSCC.v80/MS.VSIPCC.v80/MS.VSSDK.v80/dv_vsintegration/html/67aa7e1e-d84b-4273-bf43-ffbeececdcfb.htm">

See also

Developing Wizards | Defining a User Interface Value Editor | Writing Type Converters | Writing a Custom Wizard Page | Implementing Argument Value Propagation