Wojtek's Blog : GAT

New Version of GAX

Wojtek Kozaczynski — Wed, 07 Jun 2006 00:00:00 GMT

It has been a while since I posted a message, but this occasion is hard to pass; we will be releasing a new version of GAX.

Since the last release in December we have been using GAX and GAT extensively on a number of projects including the Smart Client Software Factory project (practices.gotdotnet.com/scbat) and the Web Services Software Factory project (practices.gotdotnet.com/svcfactory). Needless to say, we found some things that needed fixing and some opportunities for improvements. Here is the list of major fixes and improvements that are coming up

- GAX and GAT will now work in non-English versions of Windows

- We have fixed the annoying bug that prevented text from appearing in wizard fields if you changed the font size on the desktop to Extra Large Fonts (this one caused me a very tense moment during a demo).

- We have moved the guidance package state from the .suo file to a separate file stored in the solution root folder (this one is actually interesting and may require a separate discussion).

- We have provided a mechanism to associate ms-help pages (or plain html pages) with wizards.

A brand new feature is the Guidance Navigator. The navigator is a new VS view (by default shown as a tab in the same workspace as the Properties view) showing for each guidance package

- applicable recipes and templates (the recipes and templates that cannot be executed are not show)

- history of the executed recipes with suggested applicable next steps

- help pages associated with each recipe.

The navigator addresses a common request of the community to make the recipes and templates easier to discover and apply.

So when will the new version be available? If nothing unexpected happens, it should be available to the community in the next two weeks.

-- Wojtek

Recipes Are Not Wizards

Wojtek Kozaczynski — Sun, 29 May 2005 22:43:00 GMT

I was helping another friend design a guidance package, and I realized that he was thinking about recipes as wizards. This is not such a good idea, and may lead to misusing GAT.

Recipes are simple animals; they get information from the user and/or their environment, and execute a sequence of actions. That's it.

You can make a recipe implement a conditional flow. To do that you have to make an earlier action in the sequence provide input to a later action (through an Output property), and program that later action to take a conditional flow depending on this input. This, however, breaks atomicity of actions and will be difficult to debug.

The GAT wizard has been designed to simplify obtaining recipe arguments values. If you wanted conditional flow, you would most likely wanted a wizard to show or not show (gray out) fields depending on values of other fields. This can be done in the GAT wizard framework extension, but only with custom wizard pages. Even if you do that, you end up with Null arguments (the grayed out ones) and have to make actions behave differently depending on if they have or have no argument values (back to the previous point about breaking action atomicity).

Recipes use simple wizard mechanism to collect information from the user, but they are not like wizards. They are atomic, in that they perform a sequences of chainable, yet independent actions. They don't perform actions between wizard pages and have not been designed to execute actions conditionally.

If you think you need a conditional recipe, try to break it up into different recipes, each performing one thing. Let the user decide which recipe is applicable in what situation. Also, remember that one recipe can attach (spawn) another recipe.

-- Wojtek

Nothing Shows Up Without a Reference

Wojtek Kozaczynski — Tue, 17 May 2005 19:47:00 GMT

I was helping Eugenio write his first guidance package. He asked me to show him a few things "so he did not have to read the documentation" J. He created a project template by copying one of the existing ones, rebuilt the guidance package solution (which registered the package), and tried it. His template did not show up?! Why? Because he did not create a reference. I gave him a quick overview of what reference are for, which I have summarized below .

GAX shows recipes and templates only if it has references for/to them (so in reality, it shows references to templates and recipes). If a recipe is defined as "bound" (an attribute of the Recipe element in the config file), you need to "attach" that recipes to a solution element before it shows up. The easiest way to attach a reference to an element is to make it a side effect of unfolding a VS template (by using the RecipeReference element in the WizardData). You can also do it the hard way, using GAX services.

If you define a recipe as unbound, you have to create a reference instance yourself. This is because the instance has to implement a method that GAX calls to ask the reference if it wants to be shown on the current selection. You can also create unbound references to templates (this is what Eugenio forgot to do).

We can go into details of creating references (if we need to) in other postings. Right now, however, I would like to get back to the main point I want to make; nothing shows up unless there is a reference. This is by design. One of the key design goals of GAT was to enable guidance (recipes and templates) "only where it applies and only when it applies". References are the mechanism to achieve this goal.

-- Wojtek

A Short History of the GAT Project

Wojtek Kozaczynski — Tue, 03 May 2005 03:51:00 GMT

I though you might be interested in how it happened that PAG developed a VS extensibility mechanism. So here is a short, unedited, history of the project.

The history starts before I joined PAG two years ago. When I came onboard Scott Densmore (yes, the EntLib Scott) was experimenting with using the VS Enterprise Templates to make the PAG code-based guidance appear in VS. It was sometimes painful to see Scott trying to put a square peg into a round hole, so to speak. The main problem was that Enterprise Templates were designed to constrain what you can do, not to help you do things in the context of what you have already done. Scott's project was called Daedalus, and it was part of what we called IPE, which stood for In Product Experience.

We concluded that Enterprise Templates did not have what we needed, but we were neither ready to embark on building something else or new what that would be (yet). But here came Shadowfax, and Ed Jezierski (yes, the EntLib and CAB Ed) and I realized, that the architecture of the framework would have been simpler and easier to use, have we had a VS extensibility mechanism that would allow us to manipulate VS solution artifacts at the design time. We had a few initial ides of what that mechanism would look like, and we asked Daniel Cazzulino to build a prototype. This was bit over a year ago. The prototype came out quite interesting and promising, so we decided it was time to give IPE the second chance.

Our initial design objectives where quite lofty (aren’t they always?), and we asked the Whitehorse team to help us investigate if we should use the MDF (Meta Data Framework). This is how Stuart Kent ended up working with us for a couple of months and greatly contributed to the articulation of the key GAT concept; the recipe. It was about May last year when we prototyped enough of the design to start a development project. In PAG-speak it means that you assemble a project team and you push the project acceleration pedal all the way to the floor. The project was named IPG, which stands for In Product Guidance, and the team members were Tom Hollander (product management), Bill Loeffler (program management), Daniel Cazzulino and Oscar Calvo (development) , Ashish Babbar (testing) and your truly (architecture). The rest is, as they say, history, but this history has a few interesting twists and turns worth mentioning.

Once we realized that we were building a VS extensibility machines, we was time to go to VS team and "confessed". Our VS brethren didn't like a number of the details (parts of user experience in particular), but they did liked our ideas in general, so they assigned a, Stephanie Saad (VS core program management), to be our "guardian angel". Although not an important project milestone, this was to me a very important moment. It was the first real indication that we were up to something interesting. Over the course of next few months Stephanie helped us tremendously. In particular, when we were integrating recipes with new VS templates and we needed a few changes in VS core (aka DCRs).

Another interesting twist was deciding what GAT really was. Was it a piece of guidance, was it a product, or was it something in-between? This is where the Whitehorse team helped again. Julia Liuson, the Whitehorse team Product Unit Manger, and Jack Greenfield (yes, the Software Factories Jack), offered a home fo GAT under the emerging tools initiative. This is why you can find GAT on the VS workbenches site, next to DSL SDK.

Coming up with the "official" name was surprisingly hard. Until late in the project we were working on what we called "Recipe Framework" and what is now called guidance packages, we called recipe clusters. When confronted with the unavoidable need to give "it" a proper name, we proposed VS-IGT, that stood for VS Integrated Guidance Toolkit. I liked the name quite a bit, but techies have little to say when it comes to selecting names of things we release to communities. The marketing folks have a lot to say, and then did not like VS-IGT. After running around a number of circles, Tom finally worked out a compromise, and GAT got its name.

The last interesting tidbit (one day I will ask Stuart to write his side of the story) is that about mid way through the project (it was fall by then) the DSL SDK team and us realized, that independently we crated very similar text templating engines. Daniel wrote the GAT's T3 (stands for Text Template Transformations) and Gareth Jones form the DLS team wrote their nameless engine. The two engines were remarkably similar, so we decided to merge them. The review (Beta2) version of GAT still has T3 inside, but the Whidbey version will have the shared T4 engine (Stuart added one more T to out three Ts, so unless you know this bit of the project history, the name makes little sense).

Well, this is my recollection of what was worth sharing about the project. If I missed anything or anybody, my team member will certainly catch the omissions and blog about it.

-- Wojtek