Understanding Wizards
| 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. |
Wizards are value gathering strategies used by the Recipe Framework to gather the values of recipe arguments. Any recipe can have a wizard associated with it. A wizard walks the developer through one or more steps, which are displayed as pages of the wizard. Each page of the wizard includes one or more fields. Each field is associated with a recipe argument that it collects values for. The wizard gathers information about how to display and handle a field from the configuration of the field and the corresponding argument in the Guidance Package configuration file.
Note
Note: While wizards are the most common form of value gathering strategies, you can create your own value gathering strategy that uses a different mechanism to gather values.
Each field includes the following:
- A Type Converter. This class validates the field value and converts it from its user interface representation to a type representation.
- A UI Type Editor. This class presents the user interface that collects the information.
Initial Field Values and Value Propagation
When the wizard displays a page, it puts values of corresponding arguments into the fields on the page. In other words, it presents the user with a number of default values. These initial values of arguments are either values set when the recipe reference was created, or they are obtained by the Recipe Framework calling the value providers for all the arguments (both required and optional). This is done before the wizard is invoked.
Note
Note: Even when a recipe has value providers for all arguments, the specified wizard is always called for argument gathering and shows the default values.
Argument value providers can be defined to observe value changes in other arguments. The framework calls observing value providers when the observed argument changes value, so those arguments can also set their values indirectly. This lets you ensure that an argument is given a value based on the value of another argument.
As the user puts values into fields, other field values may be filled by the framework and the wizard. This process is known as value propagation. This is done by a combination of argument value change notifications and value providers observing other arguments change. As the user edits a field, the field value is validated and assigned to the corresponding argument. If value providers of other arguments monitor value changes of that argument, they are invoked to change the values of their arguments. The wizard is notified by the framework when argument values change, and it updates the corresponding field values.
Required Arguments
Recipes sometimes have required arguments and wizards collect the values of recipe arguments, so in some cases, fields of a wizard are required fields. The wizard framework provided with the Guidance Automation Toolkit requires the user to populate fields that correspond to required arguments. The wizard will not enable the Next or Finish buttons on a page, nor will it allow you to access later pages in the wizard from the wizard sidebar, until all fields corresponding to required arguments contain data. If an argument is not collected at all by a wizard, and the associated value provider cannot find a value, the Recipe Framework will not initiate actions and instead will raise an exception.
Note
Note: If a wizard includes fields corresponding to optional Boolean arguments, the Wizard Framework makes those arguments required, and if the argument is set to null, it changes the value to False. This allows the value of the Boolean to be set by the wizard without the user having to select and clear a check box. In this case, because the value of the field has been set, the Next or Finish button will be enabled, unless there are other, unpopulated required fields on the page.
See also
Concepts of the Guidance Automation Toolkit | The Recipe Framework | Understanding Recipes | Understanding Visual Studio Templates | Understanding Template and Recipe Associations | Understanding Launch Points | Understanding Guidance Packages | Understanding Recipe References | Understanding the Meta Guidance Package