Share via

Gathering Arguments

  • Article
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.

Each recipe definition can contain an element named <Arguments>. This element specifies the arguments to be gathered by the recipe. By default, all arguments are required, but you can define an argument as optional by setting the Boolean attribute Required to False. For more information about required arguments, see Understanding Wizards.

Arguments can be passed an initial state from a binding recipe when the recipe is spawned or in a Visual Studio template. Then you can use a combination of type converters, value providers, and value gathering strategies to gather the values of defined arguments. For more information about how value providers and value gathering strategies work, see Understanding Recipes.

Type Converters

Type converters are defined in code. They are used to validate field values, converting them from field values to the type specified in the argument. By default, arguments are of type string, but this can be changed using the Type attribute. To specify a type converter, use the <Converter> element, as illustrated in the following XML code sample.

<Argument Name="HelloMessage">
  <Converter Type="PackageNamespace.Converters.HelloWorldConverter, PackageName" />
</Argument>

For information about how to write type converters, see Writing Type Converters.

Value Providers

Value providers are defined in code, implementing the ValueProvider interface that the Recipe Framework uses to obtain the argument values. To specify a value provider, use the <ValueProvider> element, as shown in the following XML code example.

<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>

For information about how to write value providers, see Writing Value Providers.

Note

When the Recipe Framework calls argument value providers, it does so for all arguments, regardless of whether they are required or optional and whether they have a current value. When you define a value provider, you need to determine whether a value provider will replace existing argument values.

Value Gathering Strategies

In most cases, value gathering strategies are implemented as wizards. If you decide to have the user provide arguments through a wizard, you use the <GatheringServiceData> element to collect the information to define wizard fields that are used to collect the values. For more information about using this element, see Defining a Wizard.

Monitoring Arguments

In some cases, an argument will need to monitor changes to another argument. When you need to implement the monitoring of an argument, you should add <MonitorArgument> to the argument doing the monitoring, as in the following example.

<Argument Name="TargetFile">
  <ValueProvider Type="Evaluator" Expression="$(ClassName).cs">
    <MonitorArgument Name="ClassName" />
  </ValueProvider>
</Argument>

Note

<MonitorArgument> can be used in conjunction with ExpressionEvaluatorValueProvider, to ensure that an argument updates when the other argument changes. For an example of this, see The Add Main Class Recipe

See also

Developing Recipes | Defining a Recipe | Specifying Bound References | Specifying Unbound References | The AddMainClass Recipe

Developing Recipes | Specifying Command Bars | Specifying Bound References | Specifying Unbound References | The AddMainClass Recipe