[GAT]: Differencing between bound and unbound recipes

Do you have the new version of the Guidance Automation Toolkit and the Guidance Automation Extensions installed? Well, then it’s time we take off on a trip into the “zone” just like Thomas likes to say… In this case, we’re leaving to the “guidance-zone”!

So what are the possibilities? What kind of guidance package do we want to develop? What audience will it target? What procedures will it automate? That’s a whole set of questions we have to answer before starting the development phase. But we have to do something else too… Before you can start off experimenting fully with the Guidance Automation Toolkit, there are some basic concepts that one should understand well so we can take full advantage of the capabilities of the toolkit.

One of the first concepts, a true GAPD (Guidance Automation Package Developer) should master, is the diference between bound and unbound recipes. When do we use bound recipes, or when do we choose to implement unbound recipes? …

Some basic things to know…

The goal of a recipe, is automating a serie of actions, that are normally manually performed by a developer in each project. Using a recipe will ensure that these series of actions will be performed correctly and consistently. A recipe, can trigger a number of actions which have to be defined within the recipe. You can use an existing action (meaning one provided by the Recipe Framework) within the XML-file, or you can develop your own custom actions. The only key to defining your own  actions, is making them inherit the Microsoft.Practices.RecipeFramework.Action-class.
More information and an example of developing actions, will follow later…

In most of the cases, a recipe needs a set of arguments to execute its actions. These arguments can be either required or optional. We can gather these arguments in two different ways: we let the user define the argument’s value using a wizard or we can use value providers, which are implementations of interfaces that can be used by the framework to gather arguments. The strength of value providers lies in the ability to intercept changes in other arguments, so you always obtain a value that’s completely up-to-date. Value providers implement the Observer pattern in this way. When an argument which is observed, changes it’s value, it notifies all the arguments that are observing it, so they can update their values.

Getting to the different recipe types

As we all have derived from the title by now, there are two kind of recipes within the Recipe Framework: bound and unbound recipes.

A bound recipe, is a recipe that is associated with a specified Visual Studio solution element. This can be a solution, a project, a class file… The recipe will only appear in the context menu on the item you have specified to bound it to (only on solution level for example).

A bound recipe can again be recurring or non-recurring.

Easily said: a recurring recipe is like a recipe to add a test class, it wil contain a basic test method from which to start, it wil contain the correct namespace references to get you started, and so on… You can add as many test classes as you want, meaning that that specific recipe, is recurring.

When using a non-recurring recipe, once the recipe is executed, you can’t choose to execute it again. A case scenario in which you would want to create a non-recurring recipe is when you want to create a static gateway. Imagine this static singleton class only serves to hold single instances of objects and provide it for usage in other classes using properties. We could develop a recipe that would create this class, for all objects you want to instantiate just once (you could let the user choose these classes in a wizard for example). You only want to create this static gateway once, so once the recipe is executed, it is never again available. It’s possible you would want to regenerate this static singleton class, adding more or less objects in the wizard, but let’s assume in this case, you would do this in a phase of your project where this decision can’t vary.

Bound recipes are bound to a bound recipe reference. A bound recipe reference is an object used by the Recipe Framework to associate a particular recipe with a particular launch point – or speaking in Visual Studio terms, a command. The reference enables the recipe to be executed, and stores it’s state (for example, has it been executed already?).

On the other hand, we have unbound recipes. Unbound recipes aren’t asociated with any item within Visual Studio. The recipe is not “placed” on solution-, project-, nor item-level. These kind of recipes work in a whole other way. Unbound recipes are associated with unbound recipe references, and these references, selects the solution items it’s associated with or used in.

As I just said, the unbound recipe reference chooses the solution items to appear on, but it does this according to a selection condition, a so called Target Condition. This condition is written in code, thus it is defined by us, the GAPD’s. It can be a simple condition and be satisfied by a very broad number of scenarios, or quite complex thus only satisfied in very specific cases. A TargetCondition is a piece of code returning a boolean value which specifies whether the condition was met or not.

Let’s discuss a concrete example. You’re developing a guidance package, which contains a number of folders inside the Domain-project that you have predefined for usage. Since you specify an “Exceptions” folder, you want all the custom Exceptions placed inside this folder, that’s obvious. You also developed a start for custom Exception classes, which you defined as “Exception class” (which is the same as a normal class, but already inherits the ApplicationException class and contains the correct namespace instead). You only want Exception classes within the specific Exceptions-folder, but how do we enforce it???
Well, this is where the unbound recipes come to the rescue. You write a simple condition in code, which checks if the item on which the user clicked is a folder, and also checks it name…. If the recipe is satisfied, an extra command appears in the context menu of that folder: “Add new Custom Exception class”.

How does VS deal with this?

Actually I really wondered how this worked when I started with GAT. When we register a guidance package, one of the main things that happen, is that Visual Studio is told what commands we want to specify on each item in Visual Studio. In the Visual Studio world, this is not dynamic. The commands are loaded before the package, thus Visual Studio needs to know what “icons” it has to display on context-menu’s before anything. That’s why the registering process is so important (of course, this is not the only reason). The action behind the command, that’s where the guidance package comes to the scene. Olaf Conijn explained this to us on the VISUG-event about Software Factories we had a while ago.

So, what about the unbound recipes? How could this be predefined? They actually seem quite dynamic since the commands to unbound recipes are only shown if the condition was satisfied… Well, every time a solution element is selected, Visual Studio queries the Recipe Framework and calls the TargetCondition of each unbound recipe in the package. If the condition returns true, the corresponding command is displayed in the context menu. In the last sentence, I want to emphasise “displayed in the context menu”. VS uses dynamic visibility for unbound recipes. When registering a package, the items on which the unbound recipes can be available, are in deed registered. But it’s when such an item in VS is clicked, that VS adjusts the visibility of commands according to the TargetCondition of the unbound recipes.

Summary

So, I think -and hope- you now understand the difference between bound and unbound recipes.

To summarize it in a sentence, a bound recipe is a recipe attached to a particular item in your project while unbound recipes aren’t attached to any item, but contain a serie of conditions which in combination decide whether you can or not execute the recipe in a certain scenario.

Stay tuned for more GAT-talks!
Laila Bougria

GAT/GAX – Creating a guidance package

In this post we will start of with our Domain Driven Design Software Factory, the first step is obviously creating the package itself. But before we commence, I need to give some credits to my former colleague Jelle Druyts as this post is blatant plagiarism of his blog post from back in the year 2006 … but at least the pictures of this post are based on the 2008 edition of the Guidance Automation Toolkit.

To start of creating your own package, you can make use of a guidance package specifically designed for creating other guidance packages. That’s what I call eating your own dog food. So let’s generate the source for our package in a solution called Factory, which can be obtained in its current form from our codeplex team project.

The second part of this wizard allows you to set some package options like the package name, the namespace and some other information. Make sure not to include spaces in the package name as that will give issues later on.

The wizard will create us a solution with sample code for most of the elements that you can find in a guidance package, like bound and unbound recipes, templates, snippets, wizard pages and more… Besides all the sample code, there is also an installer and a setup package generated so that you can immediatly start of testing the package.  But before we can do this we need to register the guidance package. This can be done by right clicking the guidance package project and selecting “Register Guidance Package”.

In order to test your guidance package, you need to open a new instance of visual studio and navigate to the Guidance Packages section of the New Project window. As you will notice, the Domain Driven Design Software Factory has been added as a guidance package.

Note that registering the guidance package does take some time as all elements need to be reconfigured inside the visual studio environment. If you don’t have any new recipes or templates that need to be registered or if you didn’t change any HostData sections that define the integration with Visual Studio, you can get away with the “Quick Register” option which is remarkably faster.

Now let’s open a new instance of Visual Studio and lets create a sample solution and fill out the wizard.

And as a result of our guidance packages code generation, we end up with a solution that we can use to test the sample structure, templates, bound and unbound recipes.

I suggest you take a look around the generated solution if you’re not acquainted with the guidance automation packages, otherwise you can delete it again as it has obviously nothing to do with Domain Driven Design.

Next time we will start shaping our factory so that it will enforce the default Domain Driven Design layering, which has already been discussed in the Setting the scene column.

See you next time,
Yves Goeleven

Setting the scene – When identity matters

Typically the objects in a domain model can be categorized into 2 types: entities and value objects. Both of these can be implemented as regular CLS objects with properties and methods, they represent domain concepts and provide methods that manipulate the internal state. So what’s the difference then? Well, some objects require specific identity management, where a mistake in identity can lead to data corruption. Can you imagine assigning a million dollar contract to the wrong business partner? Obviously a BusinessPartner requires carefull identity management to prevent catastrophic errors in the system. These kinds of objects are called entities.

Remember that objects, when they are in memory, are identified by their memory address and not some property that acts as an identifier like this is the case in a relational database. The underlying infrastructure must ensure that the two are mapped to one another, which is often done using the identity map design pattern. Implementing such an infrastructure can be a pretty daunting task, but if you are interested, I have created an entire series of blog posts last year which covers most of the difficulties that you will encounter. Or, you could use an Object Relational Mapper instead.

On the other hand, a domain model contains a lot of Value Objects as well, which will be covered in the next post.

Stay tuned,
Yves

Setting the scene – Divide and conquer

Last time we discussed the concept of model driven design, and introduced a miniature domain model representing a Business Partner. Yet in real world applications, domain models aren’t that simple, in fact they tend to become pretty unwieldy if not extremely large. As the business domain that we are trying to capture is rather complex, it seems logical that the domain model is complex as well. Still, the practice of Domain Driven Design is trying to tackle the complexity at the heart of the matter. To prevent from having dependencies all over the place, it’s recommended to divide your domain model into distinct parts with little or no coupling between the parts, these parts are called modules. Modules should be named after business terms, in fact if the name of the module isn’t part of the Ubiquitous Language, you probably started of on the wrong foot. Even though modules are designed to reduce coupling between business concepts, dependencies are allowed, but only in one direction. It’s perfectly normal that one part of your business domain depends on another part of the same domain.

I like to represent modules with folders containing classes in the domain. In the future though I hope we can have a nice DSL that displays the domain layer with all modules as simple shapes in a domain diagram, implemented behind the scenes as folders, and that allows to drill down to the components that are contained in the module. The different types of components that can exist in a module will be discussed in upcoming articles, for now we will continue with a real life example of how to determine modules.

To determine modules one should simply look at the business domain. Currently I’m working on a contracting application for the belgian gas flow manager, so the domain is definitly contracting. Now if you think about contracts, you probably think about different Business Partners signing Agreements right? Business partners can take up different roles depending on the agreement that is signed, they could be shippers, traders, gas flow managers etc. Furthermore agreements can come in many forms: first of all there is the master agreement that says that we’re going to do business together, next we have technical agreements that limit for example the pressure of gas that is exchanged or the rules that apply for allocation of capacity to the buyer and there are many more of these kinds of agreements. But just signing a paper isn’t going to cut it! If you want to, for example, store gas, you have to make sure whether it is possible or we may blow up that nice little storage tank. So you have to ask whether you can get a certain Service at a given point or period in time, services could for example consist of rights to store gas, or to inject it, to trade it, etc…

Now if you look at the description above of a typical contracting domain for the gas flow market, one can identify a few big groups of business logic in there. These big groups, like in this example Business Partners, Agreements and Services, are what modules are all about. Note that there is a direct dependency from Services to Agreements to Business Partners, but not the other way around.

To wrap up, if your domain is rather complex ( and which one isn’t? ), split it up in different parts based on the knowledge that you have of the particular domain, but be sure to let the domain be your guide.

Next time we will start to go through the different components that can be found inside a module.

Stay tuned,
Yves Goeleven

Creating and using Visual Studio templates

We all use Visual Studio templates, day by day, even if not all of us know that they are actually called Visual Studio templates…. Just create a new project, and you’ll get to see a whole series of available Visual Studio templates that were installed along with VS itself… A C# console application project, a C# windows forms project, …, they are all Visual Studio templates…

In this post I’ll simply line out the way to create them, and how you can use them. You’ll be using this approach many times once you get going with Guidance Automation, since they are one of the key parts to defining the solutions and projects you want your package to unfold. This talk was inspired by GAT, but of course, you can use this knowledge for a lot of other scenario’s…

Event – TechDays 2008

Tomorrow (March 11th) Microsoft’s launch wave finally reaches Belgium!
3 new products (SQL Server, Windows Server and Visual Studio 2008) will be presented to the Belgian .NET community in Ghent.
The next 2 days (March 12th & 13th) will be filled with technical sessions at this year’s TechDays.

HEROES happen {here}

2 days packed with technical content, that’s what TechDays is for you. A full house of developers will have the opportunity to choose between 3 developer-oriented tracks and the architecture track. The agenda even provides some Software Factory related sessions! Some sessions that might interest you as a reader of this blog:

Title	Speaker
Domain Specific Development with Visual Studio Domain Specific Language (DSL) Tools	Jelle Druyts
VSTS Application Lifecycle management	Yves Goeleven
Application Lifecycle Management and Visual Studio Team System	Steven Wilssens

Community

As always, TechDays also provides a good medium to connect with your peers. Most Belgian user groups are present, as will quite some members of IntoFactories.NET! Be sure to meet us at the Compuware booth!

Just like last year, Visug is organizing its Visug Geek Bowling as an evening activity.
On the evening of March 12th, they’ll gather at the Bowling Palace in Lochristi around 20h!

Be there!
Stijn.

Setting the scene – Model Driven Design

Last time we spent some time separating the domain layer from the rest of the application using a Layered Architecture. This time we will take our first steps into the design of the most important layer: the domain layer.

The goal of the domain layer is to capture all the business logic that applies to the domain that we are writing software for, hence its important that the source code for the domain layer reflects the true domain as much as possible.  Why? Well, this way you can use the source code as a means of communication with all members of the team and with the eventual consumers of the application, in fact all concepts that will be discussed in the upcoming chapters should be part of this common language, called the ‘Ubiquitous Language’.

Code an sich does not lend itself very well for communication does it? It contains a lot of chatter, like point comma’s, curly braces etc… just for the sake of getting it compiled. A better way to communicate the code is using a model, a graphical domain specific representation of the code. This is where DSL’s or Domain Specific Languages come in, they can provide a graphical representation of code which is specifically tailored for the problem domain and as such DSL’s can bridge the gap between the code and the Ubiquitous Language. An excellent example of a DSL can be found in the Visual Studio Class designer, which is nothing more than a nice DSL on top of code that represents classes.

A DSL is a great way to present the concepts in a given problem domain, like the concept of a class or a workflow, as long as the concept you want to show is expressable as a graphic. But many enterprise models are just to difficult or to wieldy to capture at one glance, which is one of the biggest problems for a graphical DSL.

Next time we will look into the options we have to separate the different parts of a large model into distinct parts.

The role of Team System in a Software Factory

I’m no thought leader on the future of IT, but I do have a vision of how software development will evolve in the next couple (or hundreds) of years and Team system plays a big part in it. But before we dive into this vision, let’s have a look at what the development world looks like today.

IoC Dsl – Unity Framework

As I promised in part 1 I will give you an intro of the available frameworks that support Ioc. First in the row is the Unity Framework. This framework will be part of Enterprise Library 4.0. They just released a first CTP (can be found on CodePlex). I’m quite enthusiastic about this framework and like Mr Borat would say “Is naaizzz”.

IoC Dsl – The Beginning

First of all, before you begin to wonder what IoC Dsl stands for: IoC Dsl stands for Inversion of Control Domain specific language, not for International Olympic Committee. Secondly, IoC isn’t something new. It came from the java world (the Others …) and nowadays it’s a hot topic in .NET. IoC is something we use every day without even realizing it. It’s about loading certain implementations of an interface without you knowing in code which implementation you loaded.