My thoughts, shares ... with .Net and Microsoft - Guidance Automation Toolkit : Create a GAT Solution

Monday, April 30, 2007

Guidance Automation Toolkit : Create a GAT Solution

In a previous post I wrote about how you could create a VS2005 template. I also told you that there was a problem when using multi-project templates. This can be solved by using the GAT tool to create your template.

If you never heard about the Guidance Automation Toolkit (GAT) or the Guidance Automation Extensions, I would like to refer the Guidance Automation community site.

You are probably wondering why I’m talking about two products. Let’s make it clear. First you have the Guidance Automation Extensions. This is the runtime and must be installed on every machine that will make use of Guidance Packages. The Guidance Automation Toolkit is only needed on the machines of the architects or lead-developers or the developers who will create the Guidance Packages.

In this post I will provide you a solution for the problem with the multi-project templates. But just know that this tool can do much more than this. For example Jelle Druyts has wrote a serie Guidance Automation Series in which he will create his own application block. Txs Jelle for this great starter.

Create a Guidance Package

Start your Visual Studio and go to the New Project dialog box. You will see that after installing the GAT, there’s a new Project Type Guidance Packages. This will contain all Guidance Packages that are installed on the machine.

If not selected, select Guidance Package. Fill in a name and press OK. A dialog box will popup for some additional information about your Guidance Package.

Fill in the extra info and press Finish. The wizard will create your solution which contains 3 projects :

The Guidance Package project itself
The Guidance Package Installer
The Guidance Package Setup

Also the Guidance Navigator will be visible. At least you get a small help on how to create your Guidance Package.

Read carefully the instructions, because when you want to test your Guidance Package you have to open a new instance of Visual Studio. Also how to register your Guidance Package is described here.

So lets do a first test. Follow this steps

Build your project
Right click on your Guidance Project and select Register Guidance Package

After the registration is completed, this process takes a while, you can test it by opening a new instance of Visual Studio. The nest time in your development process you could use Quick register, which will reduce the registration time. But be aware, you could only do this only when you haven’t add any new templates or haven’t changed any of the HOSTDATA sections. HOSTDATA sections defines the integration with Visual Studio.

When opening the New Project Dialog Box you will see under the Guidance Packages a sub directory with your Guidance Package.
Start with our own Guidance Package
After playing around a bit, we want to create a Solution Template containing our pre-defined projects. First, let’s empty our project so we can start with a clean Package :

Important : Leave the 2 XML files in the project.
Delete all other files, but leave the directories.

Now that we have an empty project, we can add our first project. In our demo, we will add a C# project for the Business Layer. The next step is adding the DAL Layer project.

A good thing to know is that a Guidance Package is a combination of Visual Studio Templates and Guidance Automation Recipes. Templates are explained in my previous post. Guidance Automation Recipes are automated activities containing actions which are normally done manually by the developer. The recipes are stored in the Guidance Package XML (this is not the TypaAlias.xml). You link the two by adding a recipe reference to the .vstemplate file.

Solution template

What I did was creating a standard multi-project template and use these files to add in the Guidance Package. Be sure to set for all the objects their Build Action to Content and Copy To Output Directory to Copy Always.

If you check out the .vstemplate file, you will see that we add sections WizardExtension and WizardData to the template file. This is needed to made the connection to the recipe.

Project template

Next we need to add our template solution. In the Solution folder we create a directory Projects. Under this folder we create a folder for our solution. In here we place all our files needed for the solution. Be aware for the Build Action and the Copy To Output Directory.
We also create the .vstemplate for our project, which included also the WizardExtension and WizardData section.

Parameters

As you see in the examples we have used a parameter $SolutionTemplateName$. This is a custom parameter we can use together with other parameters (also the standard template parameter names). These parameters will be replaced during the run of the Guidance Package. They are defined in the recipe.
The Recipe
The last step after defining your templates, you need to define the recipe. A recipe will collects all user data and then start a series of automated commands. In our case we need the user to fill in the parameter $SolutionTemplateName$ and then start the creation of our solution. How to ask the user about the parameter, is done in the recipe. To do this we have to define arguments and fields for each parameter.

Running the Guidance Package

Finally everything is ready. Now we want to run the Guidance Package. To do this, we need to register out package. When this is finished, we can start another Visual Studio session. Our Guidance Package will show up under the Guidance Packages section.

Next, just like a normal project fill in the name and location and press OK. Now the Guidance Package will take over. A wizard will popup, where the user can add the info we need.

After filling in all info, press finished. Now our Guidance Package will create our solution. As you can see in the result our project has the correct name as we want and not the default defined in the templates.

Add another project

Yes, you’re sure. So much work for one project. But now we are going to add a second project. Just add all needed files to the template directory, change your root .vstemplate file.

Register your Guidance Package and test it again. You will see in the final result, that our solution now contains two projects.

From here, you can add your complete structure the same way. And now you see how much work that need to be done by the developer manually can be automated.
How to deploy to other developers
If you want to deploy your Guidance Package to other developers, follow the next steps