How To Fire a Guidance Package Recipe from the Implement Application Feature of Team Architect.

Post #01 of a collection of posts with some more technical details about the creation of richer implementations with Visual Studio Team Architect.

1

The Start: Fire a Recipe, Wizard or something else when initiating the "Implement Application" feature from the Application Diagram.

There is only one place where you can change the behavior of this feature and that is in the properties window of the selected shape. You can change the the template it uses to implement the application. Select: "Custom Template..."

2

So, we have to focus on templates [vstemplate] if we want something else to happen.

Beside the fundamental elements "TemplateData" and "TemplateContent" where you can specify the files included in the template and categorizes the template, there is also an element "WizardExtension" which can be used to run custom code and more things like:  "Display custom UI that collects user input to parameterize the template" and "Add parameter values to use in the template", actually you can perform virtually any action allowed by the Visual Studio automation object model on a project.

To use this element is easy, create a assembly which implements the IWizard interface, sign it and add it's details to the vstemplate WizardExtension element.

The IWizard interface gives us a number of methods which will fire during the execution of the template. For example:

public void RunFinished()
public void RunStarted
    (
    object automationObject, 
    System.Collections.Generic.Dictionary<string, string> replacementsDictionary, 
    WizardRunKind runKind, 
    object[] customParams
    )

You can get additional information from the replacementsDictionary parameter and can add information to it.

So, with this information you can start with coding your additions to the template, add solution folders, add projects, add items, add code. The first solution I created, to accomplish a richer implementation then the "Empty Web Site" template offers, used a list of item templates in the "TemplateContent" element. But, after the solution went bigger and I wanted to do more this didn't gave me the flexibility I needed. So, the final solution ended with only the WizardExtension which executed all the necessary steps, from project creation to adding code with the CodeDOM and references. You only have to take the DTE Object and start coding...

// The application object can be cast to the root DTE object.
dte = (EnvDTE80.DTE2)(automationObject);
sol = (EnvDTE80.Solution2)dte.Solution;

To use the IWizard interface, DTE object and the CodeDOM is pretty hard, actually it really hurts and it's not suitable to make such a big customization to your templates, for small ones it's works fine but not for this size.

So, the release of the Guidance Automation Toolkit for Orcas made things much easier.
Guidance Packages also use the "WizardExtension" element behind templates to execute additional logic as you can see in this XML snippet.

<WizardExtension>
  <Assembly>Microsoft.Practices.RecipeFramework.VisualStudio, Version=1.0.60429.0, 
Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a</Assembly> <FullClassName>Microsoft.Practices.RecipeFramework.VisualStudio.Templates.UnfoldTemplate</FullClassName> </WizardExtension>

When you dive into the "UnfoldTemplate" class you can see it also inherits the IWizard interface. So, things should work the same. Only with the GAX you get the ability to use T4 templates and all the other functionality like actions and recipes.

3

In the vstemplate there is the element "WizardData" which points to the recipe it executes during the unfoldtemplate action and with that you can use basic GAX functionality to create your projects.

<WizardData>
  <Template xmlns="http://schemas.microsoft.com/pag/gax-template"
            SchemaVersion="1.0"
            Recipe="CreateSolution">
    <References/>            
  </Template>
</WizardData>

So changing the Service Factory Modeling Edition or creating your own package starts with some customizations in this recipe, because we don't [I don't] want to see a wizard when initiating the implement application feature.

<Arguments>
  <Argument Name="SolutionName">
    <Converter Type="Microsoft.Practices.RecipeFramework.Library.Converters.RegexMatchStringConverter, 
Microsoft.Practices.RecipeFramework.Library
" Expression="[a-zA-Z][a-zA-Z_0-9]*(\.[a-zA-Z][a-zA-Z_0-9]*)*"/> <ValueProvider Type="Evaluator" Expression="$(safeprojectname)"/> </Argument> </Arguments> <Actions> <Action Name="CreateModelProject" Type="Microsoft.Practices.ServiceFactory.CustomRecipes.CreateModelProject.CreateModelProjectAction,
Microsoft.Practices.ServiceFactory.GuidancePackage
"> <Input Name="SolutionName" RecipeArgument="SolutionName"/> </Action> </Actions>

The argument captures the current selected [on the application diagram] projectname and the "CreateModelProject" action unfolds the model project template. Pointing to this changed / newly created vstemplate with in the Application Diagram will fire this recipe when using the Implement Application feature.

Next post: Collect data from the Application Diagram.

Comments (3) -

nice post!i really appreciate it.i enjoyed reading it

Thanks - Just the info I was looking for.. My search ends here..

Thanks a lot for this post

Add comment