Share via

Syntax of Visual Studio Templates

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

A Visual Studio template developed for use by the Guidance Automation Toolkit is similar to a normal Visual Studio template, but it contains additional information. The template includes a <WizardExtension> element that specifies a class in the Recipe Framework that implements template extensions for the Guidance Automation Toolkit. The following XML code example shows the <WizardExtension> element.

<WizardExtension>
<Assembly>Microsoft.Practices.RecipeFramework.VisualStudio, Version=2.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35</Assembly>
<FullClassName>Microsoft.Practices.RecipeFramework.VisualStudio.Templates.UnfoldTemplate</FullClassName>
</WizardExtension>

The Visual Studio template also contains a <WizardData> element that contains information about the recipe and template references associated with the template. The <WizardData> element describes:

  • The version of the schema that defines the <WizardData> element.
  • The recipe to be executed when unfolding the template.
  • A list of bound template and recipe references to be associated with the solution elements created by the template.

The following XML code example shows the <WizardData> element. In this case, the template never enables its Guidance Package, but creates three references: one to the HelloWorldRecipe recipe, one to the CustomWizardPages recipe, and the third to a template, named ClientApplication.vstemplate, that creates a new project.

<WizardData>
  <Template xmlns="https://schemas.microsoft.com/pag/gax-template"
  SchemaVersion="1.0"
  Recipe="CreateSolution">
  <References>
    <RecipeReference Name="HelloWorldRecipe" Target="\SampleFolder" />
    <RecipeReference Name="CustomWizardPages" Target="\SampleFolder" />
    <TemplateReference Name="Projects\ClientApplication\ClientApplication.vstemplate" Target="\SampleFolder" />
  </References>
  </Template>
</WizardData>

Note

Note: You can also add template references (and recipe references) programmatically by using an action called by a recipe. For example, the library action AddTemplateReference is used to attach a bound template reference to the selected solution element. This action is called in both the AddItemTemplateReference and AddProjectTemplateReference recipes.

A recipe reference might also have an initial state, as shown in the following XML code example.

<RecipeReference Name="RecipeWithInitialState" Target="/">
  <InitialState xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema">
    <Entry>
      <Key>StringParameter</Key>
      <Value>First string parameter</Value>
    </Entry>
    <Entry>
      <Key>IntParameter</Key>
      <Value>52537</Value>
    </Entry>
    <Entry>
      <Key>DoubleParameter</Key>
      <Value>3.1416</Value>
    </Entry>
  </InitialState>
</RecipeReference>

Note

Note: The xmlns entries support the initial state of both template and recipe references. Therefore, if you specify an initial state, it must be specified within each reference.

The body of a Visual Studio template can also include parameters that are substituted with user-provided values during template expansion. The following XML code example shows how the argument ProjectName (collected by the recipe associated with the template) is used as parameter for project template expansion.

<SolutionFolder Name="SampleFolder">
  <ProjectTemplateLink ProjectName="$ProjectName$">Projects\ConsoleApplication\ConsoleApplication.vstemplate</ProjectTemplateLink>
</SolutionFolder>

In this case, if a wizard has been used to collect a different value for the project file name, then, when the template is unfolded, the value collected will be used instead. All the parameters are of type string and the substitution is string substitution.

There are three kinds of Visual Studio templates:

  • Project templates. These templates unfold into one or multiple projects in an existing solution. They are launched from the New Project command on the Add menu of the solution or from a solution folder.
  • Solution templates. These templates can be single-project or multi-project templates. They unfold themselves into new solutions. They are launched from the New command on the File menu or the New Project toolbar.
  • Item templates. These templates unfold themselves into project items, such as classes.

Each of these templates can be associated with a recipe. This association means that when called, the wizard extension calls the recipe to let it collect parameter values (arguments) for the expansion and also execute actions that may further transform solution artifacts after template expansion. For more information, see Understanding Template and Recipe Associations.

Note

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 might be left in an unpredictable state.

See also

Developing Visual Studio Templates | Defining Solution Template | Defining Project Template | Defining Item Template