Understanding Template and Recipe Associations

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.

Visual Studio project and solution templates can have recipes associated with them. These recipes are called when the templates are unfolded. Figure 1 shows the relationship between recipes and Visual Studio templates in the Recipe Framework.

Figure 1: Relationship between recipes and Visual Studio templates

Visual Studio Templates and Recipes

If a template is associated with a recipe, when the template is unfolded, the wizard extension calls the recipe to let it collect arguments for the expansion and execute actions. This may further transform solution artifacts after template expansion. A simplified view of the flow is shown in Figure 2.

Figure 2: Unfolding a Visual Studio template with an associated recipe

The flow is as follows:

1. The template engine calls the RunStarted method of the wizard extension, passing the extension a parameter dictionary (ParmDic).
2. The wizard extension calls the value gathering wizard of the recipe associated with the template and passes the recipe argument dictionary (ArgDic) to it. The wizard interacts with the user and returns the dictionary filled with values. The dictionary may have more argument values than those required by the template. The wizard extension moves template parameter values from the argument dictionary of the recipe to the parameter dictionary of the template and returns it to the template engine.
3. The template engine expands the template.
4. The template engine calls the RunFinished method of the wizard extension. The wizard extension is the same instance that was called before, so it remembers that argument values collected by the wizard before template expansion.
5. The wizard extension calls the Execute method on the recipe and passes the argument dictionary to it. At this point, the dictionary should have all required arguments to execute recipe actions (at least the design of the recipe should be such that there should be no need to call the value gathering wizard again). However, a badly designed recipe may call the value gathering wizard again (which is shown in the flow).

Note

The unfolding of a template cannot be rolled back. This means that if there is a failure in the actions executed after a template is unfolded, the unfolded instance of a solution, project, or item may be left in an unpredictable state.

See also

Concepts of the Guidance Automation Toolkit | The Recipe Framework | Understanding Recipes | Understanding Wizards | Understanding Visual Studio Templates | Understanding Launch Points | Understanding Guidance Packages | Understanding Recipe References | Understanding the Meta Guidance Package