Simon Ince's Blog : Blueprints

Blueprints Update

simonince — Thu, 18 Jun 2009 22:40:00 GMT

This is late news as I’ve been busy recently, but if you’ve been following Blueprints make sure you read Michael’s post here. They’re evolving into something else, that I’m sure will be even more exciting...

I’ll be staying tuned so no doubt I’ll shout up when I hear more.

Blueprints Example: View-Presenter, Part 2

simonince — Fri, 19 Dec 2008 15:59:00 GMT

This article follows on from part 1, so make sure you know how far we got. Basically we can generate a project according to our required template, so next we want to be able to add a new View-Presenter enabled Web Page to the project.

We’ll do this using some T4 text templates – one for each file we need to create.

Note: Remember this is based on the November 2008 CTP, so it may not work in future versions.

Menus and Commands Primer

To allow us to do this, Blueprints has notions of Menus and Commands that work together to achieve what we want. Both are configured by right-clicking your Blueprint Factory (the “ViewPresenterFactory” project in our case) and selecting Blueprints->Edit Configuration. The Menus and Commands tabs contain configuration for each item.

A command is something that can be executed, that does the work for us. These commands can be built-in, written in C#, or declared as Windows Workflow XOML files. In this post we’ll look at writing a C# one, known as a “C# Command Extension”.

A menu is simply a way to provide an entry point to a command for the user. We specify what the menu item should be displayed as, and when it should be available. When clicked, it can invoke our C# command.

Creating a Command Extension

As with almost all Blueprint Factory tasks, we start by right-clicking our Blueprint Factory project and selecting Blueprints, this time clicking “Add Command Extension…”. Specify a name for your extension library – in my case, I chose “Commands”.

The Blueprints runtime then actually unfolds a Blueprint (the command extension Blueprint) to create a new project for you and set up a post-build copy of the Commands assembly into the ViewPresenterFactory project’s “extensions” directory. This ensures the command is included in the Blueprint package when you come to deploy it.

Next, right-click your solution and select “Project Dependencies”. Ensure that ViewPresenterFactory depends on Commands; this means that Commands will always be built first, so when you do a build the factory output will contain the latest Commands implementation.

The core of a command extension is the “ExtensionClass” class that is generated for you. You could rename this if you like – although I haven’t in this example. This class is instantiated at runtime, and the “execute” method is called with some parameters, including the name of the command to execute. Therefore, in my execute method I have code like this;

switch (command)

{

case "CreateWebPage":

CreateWebPageCommand(context);

break;

default:

break;

}

The meat of the “CreateWebPage” command is handled in another method.

What we want to do, then, is as follows:

1. Prompt for a Web Page name, such as “MyWebPage.aspx”.

2. Generate five files from T4 templates that make up the Web Page and its matching View-Presenter classes.

3. Add all five files to the host project.

These five files are;

· “MyWebPage.aspx”, to hold the HTML markup.

· “MyWebPage.aspx.cs”, to hold the code-behind.

· “MyWebPage.aspx.designer.cs”, to hold the designer-generated code behind (that a developer wouldn’t normally touch).

· “MyWebPagePresenter.cs”, to hold the Presenter class. This is stored in the Presenters folder.

· “IMyWebPageView.cs”, to define the View interface. This is stored in the Views folder.

I’ve created some helper classes to make this easy, so my command code looks pretty neat and tidy at the moment;

// create the T4 arguments

Dictionary<string, T4PropertyData> args =

new Dictionary<string, T4PropertyData>();

args.Add("ViewName",

new T4PropertyData(chosenName, typeof(string)));

args.Add("ModuleNamespace",

new T4PropertyData(env.SelectedProjectNamespace,

typeof(string)));

// build a list of files to transform

List<TransformItem> transforms = new List<TransformItem>()

{

new TransformItem(

"IView.cs.t4",

format("Views\\I{0}View.cs")),

new TransformItem(

"Presenter.cs.t4",

format("Presenters\\{0}Presenter.cs")),

new TransformItem(

"ViewPage.aspx.t4",

format("{0}.aspx")),

new TransformItem(

"ViewPageCodeBehind.aspx.cs.t4",

format("{0}.aspx.cs")),

new TransformItem(

"ViewPageDesigner.aspx.designer.cs.t4",

format("{0}.aspx.designer.cs"))

};

// perform all the T4 transforms

TransformHelper.CreateFilesFromT4(

transforms,

args,

context);

// add all transformed files to the project

// the user clicked on

List<string> files =

transforms.Select(

t => t.TargetFilename).ToList();

env.AddProjectItemsToSelectedProject(files);

We build up the list of parameters to pass to each T4 template – in my case they all need up to two parameters, which are the same for each template, and specify the name of the Web Page and the namespace. Then we build a list of templates to transform and their target filenames. This list is passed to a helper to perform the transforms themselves.

Finally, a quick LINQ statement pulls out the list of target filenames and uses another helper to add each file to the project that was clicked on.

An Example T4 Template

Before we go any further, let’s have a quick look at one of the T4 templates. These are all stored in the “ViewPresenter” folder of the Commands project. They must also be manually copied to the “content” folder of the “ViewPresenterFactory” project in order to be included in the factory package. I suspect this will change in the future, but for now, don’t forget!

<#@ Template Language="C#" #>

<#@ Assembly name="System.dll" #>

<#@ assembly name="Microsoft.SoftwareFactories.BlueprintsAPI.dll" #>

<#@ Import Namespace="System" #>

<#@ property processor="T4PropertyProcessor" name="ViewName" #>

<#@ property processor="T4PropertyProcessor" name="ModuleNamespace" #>

using System;

using System.Collections.Generic;

using System.Text;

namespace <#= this.ModuleNamespace #>.Views

{

public interface I<#= this.ViewName #>View

{

}

This template shows how the definition of the View interface is generated. I’ve declared the language of the template, and imported any required assemblies and namespaces. Note that you must have a reference to Microsoft.SoftwareFactories.BlueprintsAPI.dll as this is the host for the T4 engine in Blueprints.

The other key part of setup is declaring the properties this template depends on. In this case, we have ViewName and ModuleNamespace – they should be familiar from the setup of the T4 arguments in the command code above, in the ExtensionClass class.

Finally, the syntax of templates is very similar to ASP.NET – the use of <#= #> sections allows the injection of code that is executed when the template is processed. If you like the syntax highlighting above, I’d recommend checking out Clarius’ T4Editor Visual Studio plug-in.

Inside the TransformHelper

I’ve included the code with this post because it is simple enough to have a look through, rather than spend many words explaining here. The TransformHelper is based on the sample code generated when you first create a C# Command Extension – I’ve just tweaked it a little to suit my needs further.

The core of the task is in getting a reference to the T4 service and requesting a render;

object t4Obj = BPMServices.BPMGetResource(

new Guid(BPMConstants.T4ResourceGuid));

IT4ResourceAPI myT4 = t4Obj as IT4ResourceAPI;

if (myT4 != null)

return myT4.Render(

context,

templateText,

templateFilename,

args);

This uses some Blueprints infrastructure to get hold of the T4 service, and then executes it – notice the “args” parameter to Render is the Dictionary we created in our Command.

Wiring up a Menu

Last but not least, we need to make it possible to reach this Command. As we’ve said already, the trick is the combination of Commands and Menus.

First we must effectively “register” our new command. Open the Blueprint configuration for the factory, and click on the Commands tab. Click the “Add” button, and we can add our custom command.

We must be careful to ensure the settings on this screen match how we have created our command to be successful, so to summarise;

· “Command” should be the name of the command that you respond to in the switch statement inside ExtensionClass.execute. In my case, this is “CreateWebPage”.

· “Host” should be the full assembly name of your “Commands” project. Note that this is not “Commands.dll” (which is what I expected). The Blueprints Factory actually set mine to “ViewPresenterFactory.Blueprint.ExtensionClass.dll”. Check this by viewing the Project Properties dialog for your command extension project.

· “Class” should be the name (including full namespace) of your extension class. In my case this was easy; “Commands.ExtensionClass”.

The result is a screen that looks like this;

Next, we must make this available to the user by linking it to a Menu.

This is really easy; click on the Menus tab, and hit Add. This time, the following fields should be filled in;

· “Caption” should be whatever you want to appear on the context menu.

· “Command” must match the name of the command in the previous step, which also matches the string you check for in your switch statement in the command extension.

· “Visibility” defines when the menu option should be displayed. For now I’ve set this to “ThisProject”, which will display it as part of the context menu on the project itself (I wanted to do this at folder level but couldn’t get it to work yet). There is more information on Visibility Filters in the Blueprint Factory workflow, under “Adding context menu items and BPM extensions”.

Mine looks like this;

Done! Give the Blueprint a build and you’re ready to test it. Do this by opening a new Visual Studio instance, creating a blank solution, and then unfolding the View Presenter Blueprint into it using the Blueprints Manager from the Tools menu.

How Does It Look?

The end result is that I can right-click on the newly unfolded template project and choose to add a View-Presenter Web Page;

I then get a prompt for the name of the Web Page using a simple dialog I have written;

… and finally, a new page with a matching IView and Presenter are created for me.

I can then immediately start adding code. I’m sure you’ll see this example isn’t perfect – I can’t put pages in subfolders yet, but this is a CTP after all!

Conclusion

That’s all been pretty straightforward, but I hope it has demonstrated how quick and easy it is to get up and running with providing guidance that adds real value. I believe using approaches like this to bring consistency to development provides real tangible benefits.

Also, bear in mind we’ve done one of the trickier Use Cases of generating code – I haven’t covered just creating textual advice in the Blueprints process workflow (although the downloadable source code includes a bit), which is really really easy, yet in itself could be invaluable to many development teams.

Blueprints Example: View-Presenter, Part 1

simonince — Wed, 17 Dec 2008 14:47:00 GMT

I’m sure I’ve warned you before – I’m a big believer in Software Factories… but I’ve been quiet about this for a while now. That’s because I’ve been waiting for the ‘next big thing’… enter stage left: “Blueprints”!

I had the pleasure of attending a talk that Michael Lehman and Jezz Santos gave in Seattle a while back, and more recently I’ve spent a little time recently playing with the CTP available on codeplex, and getting a feel for how it works. I thought others might find another example useful, hence I’ve posted my thoughts here. Basically I wanted a simple example to use to generate a Blueprint, and so I chose adding a web page that adheres to the View-Presenter pattern.

If you’re after background information, you can’t miss the codeplex site, the MSDN landing page, and Michael’s webcasts.

One word of warning: This is based on the Nov 17^th 2008 CTP, so chances are it’ll break in future releases.

Creating a Template Project

The usual behaviour of a Blueprint Factory when invoked is to “unfold” a project template into your solution. By default this is a basic C# project, but we want a Web Application project with some structure in it.

To do this, we can first create a simple “ViewPresenterTemplate” Web Application project in Visual Studio 2008 as you would normally, and add “Views” and “Presenters” folders. Then implement the View-Presenter pattern on the “Default.aspx” page… the result looks a bit like this;

Next, we need to export this as a template that the Blueprints Factory can consume; so in Visual Studio select File->Export. Then export the project as a template (ensuring you don’t “automatically import…” it into Visual Studio again), and locate the new zip file.

So now we have a nice template project, we need to create our Blueprint Factory.

Creating a Blueprint Factory

Once you’ve installed all the Blueprints bits, you can access the functionality from the Blueprints Manager on the Tools menu. First create a nice blank solution, and then pop the Blueprints Manager up and choose to unfold the “Microsoft Blueprints Factory 2.1.1” Blueprint. It will then prompt you for the Project Name of the Blueprint Factory. I chose “ViewPresenterBlueprint”.

Next you can fill in some the basic details of your new Blueprint. Just fill in the Configuration tab for now. Note that the “Description” field is what is displayed to the user when selecting a Blueprint to unfold, so make it fairly explanatory.

The Template field is important for us in this example. By default, it is set to “Auto-generated”, which means when you unfold a Blueprint it will generate a new C# project for you. That’s not what we want, so we’ll come back here in two minutes.

Attaching our Template

After hitting OK you’ll see your new Blueprint Factory project all ready to go, and the guidance window (or “Blueprint Workflow”) will be displayed. Next, we need to find our template ZIP file that Visual Studio created for us. I renamed mine to “Template.zip”.

A Blueprints Factory project has a special folder to hold templates, aptly named “templates”. The easy bit, then… drag your “Template.zip” file into the “templates” folder in your ViewPresenterFactory project. It should look a little like this;

Finally, to ask the Blueprints Factory to unfold our new template instead of the default C# project, we need to edit the configuration.

Right click the ViewPresenterBlueprintFactory and choose Blueprints->Edit Configuration. Replace the “auto-generated” Template option with “User supplied”, and type in the filename of your newly added template;

Hit OK, and give your Blueprint a build.

Testing the Blueprint

At this point, you could unfold your new Blueprint into the same solution, but I prefer to do it in another instance of Visual Studio. This is because Command Extensions (what we’ll see next time) remain in memory, so you need to restart Visual Studio to unload them anyway. But I also find it doesn’t make such a mess of my factory solution’s local directory.

So, spin up a new Visual Studio, open the Blueprints Manager, pick your Blueprint and click Unfold. It will ask you for a solution to add it to, so just select “Other Project Types->Visual Studio Solutions->Blank Solution”, and give it a filename. Then you’ll be prompted for the project name for our Web Application project.

One thing you’ll find when testing is that you create a lot of these solutions (which is probably why some prefer to unfold into the same solution as the factory). Therefore I’d recommend putting them all under “C:\Testing” or something that will remind you they can be deleted.

When you unfold your new Blueprint you will see an exact copy of the ViewPresenterTemplate project we created earlier.

What next?

So far our factory doesn’t do a lot, you’re thinking! It creates a template project, and nothing else. But in the next step we’ll be taking it further... specifically by allowing a user to add a View-Presenter enabled Web Page.

Watch this space for the next post shortly.