Some of the foundations of the Microsoft Software Factories Initiative are, among others, domain-specific languages and guidance automation. This last foundation refers to automating common tasks during the development of a product that actually belongs to a family of products (or a software product line).

Let’s take game development as an example: in every game, developers should implement game screens and define game entities (main characters, enemies, etc.) following some pre-defined patterns and/or consuming some pre-defined game engines and frameworks in general. In this context, guidance automation intends to automate such tasks by enabling developers to launch them from entry points in the development environment and have all the menial/routine work to be done by the IDE.

In this previous post, I’ve presented GAT, the Guidance Automation Toolkit, as Microsoft’s approach to provide guidance automation. After the PDC 2008, in Los Angeles, Microsoft has introduced to the world the evolution of GAT, which is called Microsoft Blueprints.

From the Blueprints website: "Microsoft Blueprints […] help you codify conventions, automate tasks, ramp up quickly on new technologies and requirements, and package successful designs and implementations, so that you can use them again. […] A Blueprint is an accelerator for a specific type of software deliverable like a web service, a rich client, or a mobile application [or games!]. It supplies a process, plus resources like guidelines, patterns, templates, libraries, and tools, to help you implement the process. It’s an SDK for a problem, not a product."

You can download the October CTP version of Microsoft Blueprints and samples from its codeplex website. This post will show my own experience with the technology and hopefully will help you to ramp-up on it.

So after installing Blueprints Oct CTP on you system, you can now notice a new Blueprints Manager entry from the tools menu. That’s your starting point.

Clicking there leads you to a dialog which shows the currently installed Blueprints (software factories) in your system.

When you click on the Update button, you can add more Blueprints, either from a file or from a feed. This last option is especially cool: you can subscribe to the Blueprints feeds of specific companies, from Microsoft to "AFurtado Game Labs", to ensure you always have the latest versions of their Blueprints.

So let’s get started. To create a new Blueprint (factory), you need to launch… a Blueprint! Yes, there is a Blueprints factory that helps you to create your own Blueprints. In other words, you already have automated guidance for creating your own automated guidance. You can think of the Microsoft Blueprints Factory as a meta-factory that helps you to create your own factories. So, the same way that DSL Tools were built using DSL Tools, Blueprints are also built using Blueprints. Don’t you love the meta-meta world?

Enough talk. In this tutorial, we’ll create the foundations of a factory for Adventure Games. So let’s select Microsoft Blueprints Factory 2.0 from the Blueprints Manager window (picture above) and then click on Unfold, which is just a fancy word for creating and adding solutions, projects and projects items based on guidance automation rules.

VS then opens the "New Project" dialog. I’ll select the an empty solution so that my Blueprint projects can be unfolded in a clean environment.

Next, we need to provide a project name for the Blueprint. Let me call it "AdventureGame".

OK, now the Blueprint Editor pops up, and there we can provide more details about our factory. Let me provide some initial information in the Configuration tab and press OK.

In the Configuration tab, you can provide some information that factory consumers (product developers) will use when unfolding your Blueprint. You can even use any specific Visual Studio project template you have exported to be the initial project that appears as a result of the Blueprint unfolding. Having a XNA Studio game project would make a perfect sense for us here, but let me keep this option as "auto-generated" just for the sake of simplicity.

When you press OK, you can see that a solution and a project were created (unfolded) for you, and now the Blueprint workflow appears.

The workflow is one of the hearts of the Blueprints approach. It tells the steps that factory consumers should execute in order to implement finish their product. Two side-notes here:

• I’ve heard that it will be possible to design the workflow using WF (Windows Workflow Foundation). That would support lots of interesting things such as branches, conditions, loops, etc. However, it seems that, in this current CTP, workflows are still a linear sequence of steps.
• I foresee many opportunities here to bind workflow steps with actual "development recipes" (or tasks, or whatever you want to call it). I’m not sure which are the plans on that front but it is definitively something I’ll suggest.

So just to be clear, the workflow of the picture above is NOT the workflow your factory users will see. That workflow is for YOU, the factory/Blueprint creator, to follow. Very shortly, I’ll show you how to design our own AdventureGame factory workflow.

So I encourage you to read the workflow steps, since they provide lots of prescriptive guidance on how to carry on your factory deveopment and create your own factory workflow, menus, commands, etc. I won’t repeat what is written there but I will carry those actions in the context of our adventure games factory.

So for this exercise, let’s suppose we want to automate the way a game developer adds adventure game artifacts to the game. Examples of such artifacts are books, potions, weapons and any other item that players can grab and use in the game.

Normally, game developers would have to add a class to the solution, make it to inherit the Artifact base class, add some properties and fields to describe to artifact and so on. In the real world, lots of other (more complex) things would have to be done, including complying to game engines architecture, other patterns and implementation best practices. So just to recap our main goal here, the question to be answered is: how can we automate, for the game developer, the task of adding a game artifact?

First, let’s change our adventure game workflow. Right-click your Blueprint project and then select Blueprints -> Edit Workflow.

The Basic Workflow Editor window opens, where you can specify the steps required by the adventure game factory for game developers to create adventure games. As a best practice, the first step should be an overview of the remaining steps. So click in the first step (Overview) and then in Open Details in Word.

MS Word opens and now you can change the details that AdventureGameBlueprint consumers will see in their own Workflow window. Do your changes and save them.

Edit the other steps or add new ones at will. I’ll just add one additional step which is "Add Game Artifact". Notice you can either provide help files (.mht, .htm, .html, .doc and .docx files) to detail a step, or a URL link.

Everything looks great so far, so let’s test it. Compile your solution then launch the Blueprints Manager again from the Tools menu:

Sounds nice: our factory is already listed in the Blueprints manager and is ready to use. Let’s click on unfold and check what happens.

The dialog above asks us to enter the name of our factory instance, i.e., product. As you can see, the initial experience for consuming Blueprints is similar to the one for authoring Blueprints. Let’s enter MyFirstAdventureGame and click OK. As you can see, a new project called MyFirstAdventureGame is there and the Workflow window shows the steps we have just specified for this factory (Overview and Add Game Artifact)!

While having a product project right there for us to test and debug, in the real world, factory users (game developers) would unfold this Blueprint in an empty environment and, as soon as the unfolding is complete, they would have a XNA project ready, empowered by guidance automation to help them to complete their game development tasks.

If you right-click the MyFirstAdventureGame project, you can see a Blueprints menu is there, but it only contains the Workflow and Feedback options.

So let’s implement our final task here, which is to add a new menu item to add a new game artifact to the game, collect some information from the game developer and then add a class to our project based on such info.

Notice: if you want, you can do something much simpler than that, such as displaying a "Hello World" message box. Case you want to do that, just ignore the steps below to create a Windows Form, a T4 generation script and code to interact with the Visual Studio IDE. You’ll only need to handle the command from the generated ExtensionClass as I explain below.

A very easy way to implement commands in our factory is to right click the main factory project then select BluePrints -> Add Extension. Then you should enter a name for such kind of "extension project" that will help us to implement ArcadeGameBlueprint commands. (I’ll show you how to bind commands to menu items very shortly.)

This will (guess what?) unfold a new project in our Blueprint solution, containing the foundations for we to add a new factory command.

So since we’ll collect information from the game developer to create the game artifact, let’s create a new Windows Form and add it to the AdventureGameExtensions project. Please notice: I’m going to create such a form in a different (temporary) project and only then add it to the AdventureGameExtensions project, because it seems that a bug in the Blueprints Oct CTP doesn’t allow you to properly edit Windows Forms.

So here you have my form:

And some code-behind just to expose the values entered by the game developer:

 

Then we should copy the form to the AdventureGameExtensions project and add there a reference to System.Windows.Forms and System.Drawing.

Ok, now we need just a couple of things. First of all, we need to generate, in memory, the contents of the new class that will be added to the game developer project. For that, we can benefit from Visual Studio’s T4 technology. T4 is the Text Templating Transformation Toolkit, a text transformation technology Microsoft created to make code generation easier.

If you check the AdventureGameExtensions project, there is a MyTemplate.t4 file there ready for us to implement our code generation scripts. Let’s rename that to NewArtifact.t4 and enter the following generation script:

Even if you’ve never seen a T4 script before, it is pretty simple to understand its purpose here: I’m receiving an ArtifactName and an ArtifactDescription as parameters, while using them to name my class and to create two strings that will be returned from two class properties. The generated artifact class inherits from the fictitious class MyGameEngine.Artifact class just to illustrate the idea in the real world.

Now let’s go to the ExtensionClass and implement the behavior that will read the input from the game development using our form, call the T4 transformation using our script, and finally interact with Visual Studio development environment (DTE object) to add a new file to the current solution. The code follows below (you’ll need to add a reference to the EnvDTE assembly to make it compile):

First, we handle the switch case for the AddNewArtifact command. This will be our hook from the main AdventureGameBlueprint project (that’s the final step which will be shown very shortly). Then we instantiate the form to get user input and show it. Then, we create some T4 parameters and use the T4Transform method of a T4Helper object to call the code generation. Finally, we save the generated stuff into a temporary file and add it to Visual Studio using the DTE property of the context object, which we receive in this method.

Now we need to bind a menu item to the command implementation we have just provided. To do that, right-click your AdventureGame project -> Blueprints -> Edit Configuration. In the commands tab, add a new command called "AddNewArtifact" pointing it to the AdventureGame.ExtensionClass.dll and its AdventureGameExtensions.ExtensionClass class where we implemented the command. That is shown below:

Then you just need to create a menu entry in the Menu tab, pointing to the command, as shown below.

"ThisProject" tells that the command will be available from the adventure game project, but you could have specified other target elements in the Solution Explorer for this command to appear (such as a folder with a given name or a file with a given extension, for example).

Finally, add the NewArtifact.t4 file to the content folder of the AdventureGame project and you’ll be ready to go.

Now let’s test it! Compile your project, open a new instance of Visual Studio and unfold an AdventureGameBlueprint blueprint. Right-click you solution and notice that the Add New Artifact… menu will be there!

Clicking in this menu entry will launch our form to collect game developer information, as expected:

And, finally, after entering the info and pressing OK, VS will unfold our code generation script and add a new class for that game artifact to our project.

Sweet, isn’t it? Now imagine that, if instead of adding an artifact class to our project based on user input, we had a much more complex task required to be executed many many times by game developers. Can you imagine how much development time things like Blueprints, DSL Tools and code generation technolgies can save in such scenarios? Me too!

You can download the source code here. Hope to keep bringing interesting software factories/automation content often.

[]s
— AFurtado

The statements or testimonies I offer in this post represent my own personal views.
I am speaking for myself and not on behalf of my employer, Microsoft Corporation.