In days of yore you would simply use the [ToolboxBitmap] attribute and define a bitmap for your custom tools (an activity is just another tool in this instance), and when adding a tool to the toolbox you can optionally specify an icon – however if you don’t then you get the standard ‘cog’ on screen…

If you want however to display the correct icon for a given activity you’ll need to do a bit more work and that’s where the fun starts. The images for the inbuilt activities are held in a couple of places – one is inside the Microsoft.VisualStudio.Activities.dll (which you’ll typically find in C:\Program Files (x86)\Microsoft Visual Studio 10.0\Common7\IDE) however that’s not redistributable – but it does include bitmap images of each activity and these are what’s used within Visual Studio.

The other is within the System.Activities.Presentation.dll which is redistributable, however this contains XAML resources and not standard bitmaps – and [ToolboxBitmap] expects an image resource not a slab of XAML.

Now, we’re in the world of XAML so using a bitmap resource seems a bit old hat – I’d much rather use a scalable vector icon representation so this post will show how to do this. The following steps will guide you through the process.

Step One: Add the workflow resources to your application

Edit your App.xaml.cs (or anywhere else you wish for that matter) and insert the following code – this will add the standard icon resources from System.Activities.Presentation.dll into your applications resource directory…

ResourceDictionary dict = new ResourceDictionary { Source = 
  new Uri("pack://application:,,,/System.Activities.Presentation;V4.0.0.0;31bf3856ad364e35;component/themes/icons.xaml") };
this.Resources.MergedDictionaries.Add(dict);

Note here that I have included the full pack: specification for the assembly, including the version number and public key token. In my application it would work fine without these whilst debugging, however if the debugger wasn’t attached this would fail without the fully qualified assembly information.

Step Two: Create a converter

We’ll use this converter to lookup the appropriate icon resource from the above resource dictionary at runtime, in order to present this on screen. If you disassemble System.Activities.Presentation.dll in Reflector and look at the resources (using the BamlViewer add-in) then you’ll see the naming scheme is just the activity name + ‘Icon’…

This is just a snippet of the themes/icons.baml resource, and you can see from the above there are some other things in there that aren’t necessarily activities (and interestingly enough there are some resources for activities no longer in WF4).

So, all our converter needs to do is lookup the typename of the activity, then append ‘Icon’, then go hunting in the resource dictionary and finally return the content of the DrawingBrush…

public class ToolboxItemWrapperIconConverter : IValueConverter
{
    public object Convert(object value, Type targetType, object parameter, CultureInfo culture)
    {
        ToolboxItemWrapper wrapper = value as ToolboxItemWrapper;

        if (null == wrapper)
            throw new ArgumentException("Expecting a ToolboxItemWrapper as the converter parameter", "value");

        // Generate the resource name
        string resourceName = string.Concat(wrapper.Type.Name, "Icon");

        // And lookup in app resources
        DrawingBrush icon = App.Current.Resources[resourceName] as DrawingBrush;

        if (null != icon)
            return icon.Drawing;
        else
            return null;
    }

    public object ConvertBack(object value, Type targetType, object parameter, CultureInfo culture)
    {
        throw new NotImplementedException();
    }
}

This converter isn’t quite finished yet – if you happen to add on an activity to the toolbox such as FlowSwitch<T>, you won’t get an icon for that as shown below…

And you might notice that Flowchart is missing it’s icon too. That’s easy to sort – the actual name in the resources is FlowChartIcon (notice the capitalisation) – so I’ll special case that one in my converter. If you happen to care, TransactedReceiveScope is also one that I’ve special cased as its name doesn’t match the pattern either. As for the generic types, their icons are simply named without the generic parameter – so in the case of FlowSwitch<> this would be FlowSwitchIcon. Another bit of code is needed in the converter to deal with these generic activities.

Step 3: Re-style the toolbox

In order to display your XAML icons in the toolbox you need to re-style the toolbox and use the converter to provide the correct icon for the activities. Here’s some XAML to get you going…

<Style TargetType="{x:Type sapt:ToolboxControl}">
    <Style.Resources>
        <local:ToolboxItemWrapperIconConverter x:Key="iconConverter" DefaultResource="GenericLeafActivityIcon"/>
    </Style.Resources>
    <Setter Property="ToolTemplate">
        <Setter.Value>
            <DataTemplate DataType="{x:Type sapt:ToolboxItemWrapper}">
                <Grid>
                    <Grid.ColumnDefinitions>
                        <ColumnDefinition Width="Auto"/>
                        <ColumnDefinition Width="*" SharedSizeGroup="toolLabel"/>
                    </Grid.ColumnDefinitions>
                        
                    <Rectangle Width="16" Height="16" Margin="4">
                        <Rectangle.Fill>
                            <DrawingBrush Drawing="{Binding Converter={StaticResource iconConverter}}"/>
                        </Rectangle.Fill>
                    </Rectangle>

                    <TextBlock Text="{Binding DisplayName}" Grid.Column="1" VerticalAlignment="Center"/>
                </Grid>
            </DataTemplate>
        </Setter.Value>
    </Setter>
</Style>

This style defines a couple of grid. columns, one for the icon and another for the name of the activity. I’ve set a size of 16 * 16 for the icon size however as this is your XAML you could change this for something larger if you so desired. You might also want to define a nice looking tooltip and, again, as it’s XAML you could go mad!

In the above I’ve set the default activity icon to “GenericLeafActivityIcon” which is the default that Workflow uses when displaying activities with no icons defined. You' may wish to change this for something else – but it’s also the default used in the workflow designer too so it’s not a bad choice.

Step 4: Icons for your custom activities

OK, that’s all the standard activities dealt with – what about your own? There are two things you need to do in order to get your custom activities to play nicely with the toolbox and also the designer surface. First off you’ll need to design an icon for your activity – I can’t help with that other than suggesting you have a play with Expression Design.

Then you can do one of two things – either alter your activity designer and specify an Icon for it there, or ensure that you have an icon resource using the same naming convention used above – i.e. “TheNameOfYourActivity” + “Icon”. I’d suggest you do both – my converter will look for a resource following the naming pattern convention first, and if that’s not found it then looks for the icon on the associated designer. In order to do this however it has to construct an instance of the designer which isn’t really that good an idea, so I’d recommend the naming convention approach first.

To change the icon for the designer, all you do is specify it in the XAML for the designer…

<sap:ActivityDesigner 
    <snip> 
    Icon="{StaticResource IfIcon}">

Naming the icon in your custom designer isn’t really an optional step as if you don’t do this your activity will show the default image on the design surface.

With all that done you can now see the appropriate icons in the designer…

Now that’s looking much better! The full source code for the converter is available here.

Last but not least, if you’re wondering why I didn’t choose the cog icon in the toolbox it’s not a XAML resource so I went with the default XAML one instead.

Cogs banished.

As an example, their instrumentation data can be grouped (it’s all in SQL) to produce a summary table something like the following…

So, we used these percentages to define the test mix in Visual Studio. Then we ran some short tests and I wanted to be able to output something similar from the actual results in the load test database in order to compare them.

The new Export To Excel tool is excellent in VS2010 for comparing one run to another, but I didn’t want that – I wanted to compare a run to my existing data. In my simple mind, if I have 3 months of calls (for 200 users), then I can use a short load test using the percentages defined to work out how many calls the system will make in, say, 8 hours. I can then extrapolate this out to 3 months, and say (with a reasonable degree of accuracy) that the system should be able to support more users.

My problem however was getting the data out of the load test database in a form that was usable to me. I’m a big fan of referential integrity in the database, as not only does it ensure that you can’t bung in data that is nonsensical, but tools such as SQL Management Studio can extract the schema and show you the links. After some poking around in the database I identified the two tables that were of use to me. Needless to say there were no foreign keys between these tables which is most probably due to insert performance (i.e. recording tests as fast as possible). Oh well. They are as follows…

There’s also the LoadTestRun table which is the root as far as tests are concerned, and from that you can get the date/time of the test run and other data (such as the description of the test once you’ve annotated your run). A quick select on this table will give you a list of all the load tests you have executed, and from this you need the LoadTestRunId…

      SELECT * FROM LoadTestRun

With the unique load test ID it’s a simple job to then select the summary data. I created a stored proc to do this as follows…

CREATE PROCEDURE GetTestSummary (@loadTestRunId INT) AS
BEGIN
  SET NOCOUNT ON
  SELECT LTC.TestCaseName, LTTSD.TestsRun, ROUND(LTTSD.Average,2) AS 'Average (s)', 
         ROUND(LTTSD.Minimum,2) AS 'Minimum (s)', ROUND(LTTSD.Maximum,2) AS 'Maximum (s)', 
         ROUND (LTTSD.Median,2) AS 'Median (s)'
    FROM LoadTestTestSummaryData LTTSD
    INNER JOIN LoadTestCase LTC
      ON LTTSD.TestCaseId = LTC.TestCaseId
      AND LTTSD.LoadTestRunId = LTC.LoadTestRunId
    WHERE LTTSD.LoadTestRunId = @loadTestRunId 
    ORDER BY LTC.TestCaseName ASC
END  

This produces just the output I was looking for…

So, I can now extrapolate these figures out to see how many of these tests could run in three months, and from that work out what the likely user load the system could handle would be. It’s not perfect as table sizes will change, but it will give me a good ballpark figure.

One other very useful piece of data we can also extract from the customers instrumentation is the timings (as luckily these were recorded). I can then use the frequency of calls and the execution times to judge which methods I should really concentrate on tuning.

Hope this helps someone.

When installing the load test controller I specified the machine name as '.'. Nothing in the setup told me this would be a problem, but it was. When I then ran my tests I received the following error from Visual Studio...

For the benefit of search engines the full text is repeated below...

Could not read result repository: Could not access the load test results repository: A network-related or instance-specific error occurred while establishing a connection to SQL Server. The server was not found or was not accessible. Verify that the instance name is correct and that SQL Server is configured to allow remote connections. (provider: Named Pipes Provider, error:40 - Could not open a connection to SQL Server).

Will display the runtime result instead of the repository result.

I checked everything. SQL Server was installed correctly, all network protocols were enabled, I could access the server remotely, but still the error persisted. After some head scratching Rob suggested I change the server name from ‘.’ to the actual name of the server…

Sure enough that did the trick. I can now read the results. Interestingly enough my previous runs were written to the database correctly, it’s just that I couldn’t read them from Visual Studio without making the above change. I’ll chalk that up to experience, good to know the problem though. I would have appreciated it if the wizard had told me that ‘.’ would cause problems down the line mind you.

I was on site with a customer today writing some custom activities and found a problem that wasn’t immediately obvious how I could get around it (and indeed it’s taken me some hours of head scratching and debugging to finally find the answer).

I have a custom activity on which I’ve defined the following property…

public Comparison Comparison { get; set; }

The comparison class is one I’ve made up myself, and I have derived classes such as BooleanComparison, StringComparison and so on. The actual value of the Comparison property is set by my designer. In the designer I then want to show the appropriate UI for each type of designer, so I created some data templates…

<DataTemplate DataType="{x:Type helpers:Comparison}">
    <TextBlock Text="BOOL"/>
</DataTemplate>

<DataTemplate DataType="{x:Type helpers:StringComparison}">
    <TextBlock Text="STRING"/>
</DataTemplate>

<DataTemplate DataType="{x:Type helpers:DateTimeComparison}">
    <TextBlock Text="DATETIME"/>
</DataTemplate>

OK, so these are hardly going to set the world on fire, but you get the idea. I then databound the Content property to a ContentPresenter so…

<ContentControl Content="{Binding ModelItem.Comparison}"/>

But on screen this never worked – I kept on getting the TypeName show up – a sure sign that the right data template wasn’t being selected. Puzzled, I fiddled around for some hours trying to solve this. I thought I must have the XAML wrong, so popped the lot into a new WPF project but it all worked as expected. Even more puzzling. I then decided to move the property into the designer, which changed the binding from ModelItem.Comparison to just Comparison, and lo & behold it now worked.

Knowing a bit about how ModelItem worked under the covers (it’s a custom type converter) I twigged – the object returned from ModelItem.Comparison wasn’t a real Comparison object (or rather, it was wrapped in something, which just so happened to be the ModelItem class).

So, armed with this I knew I was just about there, and a quick stint in Reflector told me I should call the GetCurrentValue() method of ModelItem in order to get the actual value for my binding. So I crufted up the following converter and now all is sweet in Workflow land for me – all I have to do is add on the converter to my binding and it’ll then find the appropriate data template.

<ContentControl Content="{Binding ModelItem.Comparison, Converter={StaticResource modelItemConverter}}" />

The converter class is shown below – it’s trivial to implement but this will save you typing a few lines!

public class ModelItemConverter : IValueConverter
{
    public object Convert(object value, Type targetType, object parameter, System.Globalization.CultureInfo culture)
    {
        object retVal = value;

        if (value is ModelItem)
            retVal = ((ModelItem)value).GetCurrentValue();

        return retVal;
    }

    public object ConvertBack(object value, Type targetType, object parameter, System.Globalization.CultureInfo culture)
    {
        return value;
    }
}

Hopefully this will save someone some time!

We have a bunch of machines, and my customer has created a set of custom performance counters that report appropriate data. The goal based test was setup to utilise a custom counter on a remote machine, but when we ran the test we got the following exception…

A goal based load pattern can not be applied because it specifies a performance counter (UKGC08\Availability Searches\Operations Executed / sec\) that could not be read: Category does not exist.

Here UKGC08 is the machine name that the counter was defined upon, “Availability Searches” was the category and “Operations Executed / sec” was the counter name. There was no instance specified.

In addition to the above error I also received a stack trace…

at Microsoft.VisualStudio.TestTools.WebStress.LoadTestResultsCollector.AddOrReplaceGoalProfile(LoadTestGoalBasedLoadProfile goalProfile)
at Microsoft.VisualStudio.TestTools.WebStress.LoadTestResultsCollector.AddGoalProfilesFromLoadTest(WebTestSuite suite)
at Microsoft.VisualStudio.TestTools.WebStress.LoadTestResultsCollector.Start(LoadTestRigInfo rigInfo, TestRun testRun)

Looking into the code in AddOrReplaceGoalProfile I found the error – internally this creates an instance of the PerformanceCounter class in order to read the data from this counter. The problem is that the code is currently written as follows (and thanks again to the most excellent Reflector for decompiling this for me)…

PerformanceCounter counter;

if (string.IsNullOrEmpty(goalProfile.InstanceName) || string.Equals(goalProfile.InstanceName, SINGLE_INSTANCE_NAME, StringComparison.OrdinalIgnoreCase))
    counter = new PerformanceCounter(goalProfile.CategoryName, goalProfile.CounterName);
else
    counter = new PerformanceCounter(goalProfile.CategoryName, goalProfile.CounterName, goalProfile.InstanceName);

counter.MachineName = goalProfile.MachineName;

The issue is that the machine name is not defined on the constructor of PerformanceCounter, and hence an exception is thrown as this code is not running on the machine that the counters are defined upon which will be the local machine or the load test controller.

I’ve raised this with the product team and they’re raising a bug internally, but in the meantime is there a workaround?

Well yes, as it happens. The code above is looking for the custom counter on the wrong machine – so the workaround is to install the counters everywhere, not just the machine under test. All I did was take the customers counters, install these locally (and on the controller, as to be fair I’m not sure which machine is running this code and didn’t test each machine individually) and voila, it all works. In the absence of a formal fix this workaround will get you running. Hope this helps!

Firstly you need a custom designer. Once you have a designer, open up the code behind file and create a new property of type ICommand.

/// <summary>
/// Custom activity
/// </summary>
public partial class CustomSchedulerDesigner
{
    /// <summary>
    /// Command used to add a banch to my activity at design time
    /// </summary>
    public ICommand AddBranch { get; set; }

}

My activity has branches (in a similar concept to the Pick activity and the Parallel activity) so AddBranch seemed like a fairly reasonable name for the command. Some folk subscribe to the notion that all commands should be suffixed with ‘Command’, so if you would prefer please feel free to call yours AddBranchCommand. Me – I’m fine with the above.

Next you need an implementation of ICommand to actually do the work (and optionally enable/disable the command). What you choose is up to you – I use a DelegateCommand class that I’ve had hanging around in my snippets in VS for a year or two, you may have your own but if not a quick search on the web will bring up many DelegateCommand classes. So, I then need to add a delegate command that will be called when the user clicks my menu item. For my example the code is as simple as the following…

/// <summary>
/// Custom activity
/// </summary>
public partial class CustomSchedulerDesigner
{
    /// <summary>
    /// Command used to add a banch to my activity at design time
    /// </summary>
    public ICommand AddBranch { get; set; }

    public CustomSchedulerDesigner()
    {
        InitializeComponent();

        AddBranch = new DelegateCommand(x => 
            this.ModelItem.Properties["Branches"]
            .Collection.Add(new CustomSchedulerBranch()));
    }
}

Here I’m using a Lambda expression for the delegate (I love ‘em) and it looks up the Branches property of my custom activity, and to it adds a new instance of the CustomSchedulerBranch activity. The ModelItem property of a custom designer isn’t strongly typed hence the somewhat weird syntax, but you could do some work to get the actual activity instance if you wished. I took the quick route!

With that little lot in place all you then need to do is wire up the command inside the designer. In my XAML I added the following…

<sap:ActivityDesigner.ContextMenu>
    <ContextMenu>
        <MenuItem Header="Add Branch" Command="{Binding AddBranch}"/>
    </ContextMenu>
</sap:ActivityDesigner.ContextMenu>

And then you can compile your code and you should see a new menu item on screen when you display the context menu over your activity…

Voila! Clicking on the “Add Branch” menu item calls your delegate and you can then do whatever you wish within the designer code. I’ve not provided an example as mine’s been hacked around a bit but hopefully there’s enough here to make it fairly easy to follow along. The jaunty tilt in the image above is a feature of Windows Live Writer, which I use to create my blog posts. I just noticed that I could tilt images so couldn’t resist.

Bye for now!

public class WibbleViewModel : BaseViewModel
{
    public WibbleViewModel()
    {
        _thisCommand = new DelegateCommand(x => 
            MessageBox.Show("You clicked ThisCommand"));
    }

    public ICommand ThisCommand
    {
        get { return _thisCommand; }
    }

    private ICommand _thisCommand;
}

ICustomTypeDescriptor to the rescue

Rather than repeat this code ad-infinitum for each command (and lets face it, WPF apps generally have lots of commands), I crufted up a sample using a custom type descriptor. If you don’t know, .NET has supported the ICustomTypeDescriptor interface since the first version (indeed I wrote an article about extending the Windows Forms property grid that used ICustomTypeDescriptor on 30/11/2001!). What this interface allows you to do is to synthesize metadata about an object instance. You can for example add attributes to the metadata for an object using this interface. You can also add fields. But for the purposes of this article, I’m adding properties.

What’s the good of that you might say?

Well, what I’m trying to do is simplify the number of lines of code I have to write in order to expose commands on a given View Model. Now, when I bind to a command from the XAML I’d typically type in an expressions such as the following…

<StackPanel Grid.Column="1" Orientation="Vertical">
    <Button Content="New Expense Claim" Margin="30,10"
        Command="{Binding NewExpenseCommand}"/>
    <Separator/>
    <Button Content="Approve Claim" Margin="30,10"
        Command="{Binding ApproveExpenseCommand}"/>
    <Button Content="Reject Claim" Margin="30,10"
        Command="{Binding RejectExpenseCommand}"/>
</StackPanel>

Then for each of these 3 example commands I’d have to define a property getter, private variable etc etc. Now Binding in WPF is pretty clever, and it uses property descriptors in order to navigate to the value bound.

Less Code, More Smiles

So, all I should need to do is alter the syntax used in XAML and (with the assistance of a helper class) I could expose commands *without* all of the boilerplate code. I’d then have bindings setup as follows…

<StackPanel Grid.Column="1" Orientation="Vertical">
    <Button Content="New Expense Claim" Margin="30,10"
        Command="{Binding Commands.NewExpenseCommand}"/>
    <Separator/>
    <Button Content="Approve Claim" Margin="30,10"
        Command="{Binding Commands.ApproveExpenseCommand}"/>
    <Button Content="Reject Claim" Margin="30,10"
        Command="{Binding Commands.RejectExpenseCommand}"/>
</StackPanel>

Note here that I’ve prefixed the name of each command with ‘Commands’. This is a property that I’ve exposed from my View Model that uses my CommandMap class (which you can grab at the end of the article). The entire code in my View Model to expose the three commands is as follows…

public class WibbleViewModel : BaseViewModel
{
    public WibbleViewModel()
    {
        _commands = new CommandMap();
        _commands.AddCommand("NewExpenseCommand", 
            x => MessageBox.Show("Not yet implemented", "New Expense Claim"));
        _commands.AddCommand("ApproveExpenseCommand", 
            x => MessageBox.Show("Not yet implemented", "Approve Claim"));
        _commands.AddCommand("RejectExpenseCommand", 
            x => MessageBox.Show("Not yet implemented", "Reject Claim"));
    }

    /// <summary>
    /// Get the list of commands
    /// </summary>
    public CommandMap Commands
    {
        get { return _commands; }
    }

    private CommandMap _commands; 

}

Here I’ve created an instance of the CommandMap class in my constructor, exposed this as a read-only property, and then created the actual commands in the simplest way possible by calling ‘AddCommand’. There are two overloads of AddCommand as shown below…

public void AddCommand(string commandName, 
                       Action<object> executeMethod);

public void AddCommand(string commandName, 
                       Action<object> executeMethod, 
                       Predicate<object> canExecuteMethod);

The commandName argument is used to expose the ICommand to the {Binding} markup extension. If you remember, in the XAML I bound to Commands.NewExpenseCommand which, through the beauty of ICustomTypeDescriptor, ultimately gets me into my code that can return an ICommand instance. The {Binding} extension first looks for an object called Commands on the current DataContext. This gets me to my CommandMap class. The binding then asks for the NewExpenseCommand property, which is now running code in my custom type descriptor code. All I have to do is delve into a dictionary inside CommandMap that stores name/value pairs based on what I used for AddCommand, and I can synthesize a property called NewExpenseCommand (or anything else for that matter) which WPF will diligently bind to. Voila!

The executeMethod and canExecuteMethod properties can be supplied as Lambda functions, making your code nice and concise (under the covers I’ve reused a DelegateCommand object which I’ve been using for ages). And just for that extra bit of conciseness (if that’s a word!) I could move all of this stuff up into the BaseViewModel class. Saweet.

The Code

Please click on the following file to view or download the C# source code for the CommandMap class.

CommandMap.cs

This doesn’t have any other dependencies so you should be able to plug this in wherever you like with the minimum of fuss. The one enhancement I can think of at the moment is to cache the property descriptor collection returned from the GetProperties method of the CommandMapDescriptor class. This would require that the command collection was an observable collection and I’ve just not got round to that code as yet.

Let me know what you think – good/bad/ugly?

My example models access control to a door – the host is a WPF application (which could do with some better styling!). Imagine if you could ‘boot’ up a building. In that case each door would for sake of argument be closed and locked – this forms the initial state of the state machine. Thereafter we’re awaiting an event, which is the user unlocking the door. This might be by using a PIN pad or a smart card – the details of this are beyond the scope of the post. An overview of the states and transitions is shown in the image below.

When the user presents their credentials the Unlocked transition occurs – here you could optionally pass the PIN number (or card entry code) into the transition to lookup the code in a database and verify that it is correct. In my example I just transition to the ClosedUnlocked state without any verification.

From this state there are 3 possible things that could happen – the user could open the door (the most likely outcome), they could choose to re-lock the door for some reason, or they might not open the door within a set period in which case you would want the door to automatically re-lock itself and transition back to the ClosedLocked state. So at this point there are 3 transitions executing, two are waiting on an event (more on this in a moment) and the third (Timeout) is waiting for a Delay which in my example is 5 seconds. I’ll explain a little more about the State and Transition classes as they are critical to understanding how the state machine works.

States & Transitions

A state machine comprises a collection of states and a collection of transitions between states. There’s always one initial state, and you can optionally have a final state (which completes the execution of the workflow instance). When you enter a state you can optionally run some activities, and similarly when you exit a state you can also execute some activities. To define the entry and exit activities, double click on the state in the designer which will show something like the following (I chose the ClosedLocked state from the above diagram)…

When a state activity executes it calls the Entry activity (which can of course be a Sequence so that you can run multiple activities) and we then find all outgoing transitions. We then execute each transition, which in the case of my state machine example executes a set of activities that create a bookmark and then wait for this bookmark to be resumed. This may seem a bit odd – if you have 3 transitions we schedule the Trigger activity (shown in the image below) for each of the 3 branches. When the state machine engine then does is waits for one of these activities to complete, and whichever gets in first will ‘win’ and that transition will complete.

Possibly the easiest way to view transitions is as a Pick activity. When you are in a given state, we effectively execute each transition branch in a similar manner to that of the Pick activity, and the first activity to complete will complete the transition. You can optionally include a Condition on the transition which is evaluated when the trigger event occurs and the transition is only completed if the condition returns true. In the ClosedLocked state we’re effectively waiting as follows…

I’ve omitted any Actions in the above as the transition branch works in a slightly different manner to Pick. When the transitions Trigger activity completes (and assuming the condition evaluates to true) we’ll also execute the Action activity if you’ve created one.

So, in a state we’re waiting for an activity to complete, and in the above image I have a custom activity shown as the DoorUnlocked and DoorLocked activities. These are instances of the DoorEvent activity which uses a bookmark that can be resumed by the client. The code for this activity is fairly trivial and is shown below…

public class DoorEvent : NativeActivity
{
    protected override bool CanInduceIdle
    {
        get { return true; }
    }

    [RequiredArgument]
    public InArgument<string> BookmarkName { get; set; }

    protected override void Execute(NativeActivityContext context)
    {
        context.CreateBookmark(BookmarkName.Get(context), new BookmarkCallback(OnBookmarkResumed));
    }

    private void OnBookmarkResumed(NativeActivityContext context, Bookmark bookmark, object state)
    {
    }
}

Not a great deal going on there really – it has a mandatory BookmarkName property which defines the name of the bookmark we’re using. In the example, the name of the bookmark matches the transition label.

Hosting in WPF

In the example I’m using a WPF host, and using the MVVM pattern (here with only a View Model) to maintain the user interface. The UI needs to know what state the state machine is in in order to resume appropriate bookmarks, so in each state activity I pass the state out to the View Model using another custom activity. This updates a property on the view model which in turn enables/disables parts of the UI.

There are a couple of classes used in the example for view models – the MainViewModel class is the root of the application, and it contains a set of DoorModel instances, one for each door shown on the UI. When a DoorModel is created it creates a WorkflowApplication instance and adds an extension to the instance (IDoor) that the door model implements. It is this extension that the workflow calls back to the door model on when notifying state changes. The pseudo code for the system is shown below…

• The DoorModel instance is created. I set its name (shown on screen).
• An instance of the state machine is created inside a WorkflowApplication instance. This is passed an interface back to the door model that owns it (IDoor).
• The state machine starts up and immediately executes the first state activity ‘ClosedLocked’. This executes the SetDoorState activity which calls IDoor.SetState() and passes an enum value to the method to indicate what state the machine is in.
• The UI is updated to enable/disable commands as appropriate based on the state of the workflow.

Thereafter the UI is in charge of the state machine. When a command such as ‘Unlock’ is executed, it simply resumes the appropriate bookmark on the state machine…

_unlockCommand = new DelegateCommand((unused) =>
    {
        _stateMachine.ResumeBookmark("Unlocked", null);
    },
    (unused) =>
    {
        return this.DoorState == DoorState.ClosedLocked;
    });

Here I’m using a DelegateCommand class so that I can use lambda functions to respond to the command (and also to define whether the command is valid or not based on the current state).

That’s pretty much all there is to it – as the user clicks around on the UI it executes the appropriate command, this resumes a bookmark which will then force a transition in the workflow, and when a new state is entered this calls back to the view model to indicate the new state. Simple.

There’s one other part of the application I wanted to call out and that’s the use of a custom PlaySound action on each transition. This simply plays a sound to indicate the state of the door (well, sort of!) when the transition completes. As an example there’s one sound used when the timeout happens but another when the door is manually locked. I initially defined these sounds in the ‘Entry’ element of each State activity, but this didn’t indicate the particular transition that had just occurred – i.e. there was no way to distinguish how the state machine had transitioned to the ClosedLocked state to allow me to play a different sound on entry to that activity.

When you run the application you’ll see the following wonderful UI…

If you click on the Unlock button the workflow executes and changes the state to ClosedUnlocked. You’ll also see a couple more buttons show up that correspond to the now valid states (Lock and Open). If you unlock a door and then leave it for around 5 seconds the door will automatically lock again. For all transitions you’ll also be rewarded with some sounds – if these don’t work check the PlaySound activities in each transition and choose your own files to play (I’m on Windows 7 so the directory and files might be different from your machine).

The Code

Click here to download the source code and VS project. Feel free to tart up the user interface!

• You wish to drop a number of related activities, in a similar manner to when a Parallel is created and within it two branches are created for you
• You have an item which is not an activity that you would like to drop onto the designer surface (such as the PickBranch)

When you create custom activities, Visual Studio will automagically add these to the toolbox (as long as they are within the same solution file). When you drag and drop an activity this activity is added to the designer. You can however augment this behaviour by implementing the IActivityTemplateFactory interface, which is used in preference to construction of the actual activity.

So, you can create a placeholder activity that shows up on the toolbox, but when it’s dropped it constructs an entirely different sent of activities on the designer surface. All you do is implement the Create method of IActivityTemplateFactory and within this you can then create any activities (and optionally hook these together as you need).

Stage 1 – Dropping related activities

First up create a Workflow Console Application and then add an Activity Library project to the same solution. You can remove the Activity1.xaml file as we’ll not need that. Then add a reference to both the WindowsBase and also System.Activities.Presentation assemblies.

Next you can code up the Create method. An example is shown below…

public class Dropper : Activity, IActivityTemplateFactory
{
    public Activity Create(DependencyObject target)
    {
        Pick pick = new Pick();
        PickBranch item = new PickBranch();
        item.DisplayName = "Branch1";
        pick.Branches.Add(item);
        PickBranch branch2 = new PickBranch();
        branch2.DisplayName = "Branch2";
        pick.Branches.Add(branch2);
        return pick;
    }
}

I shamelessly stole the code above from the PickWithTwoBranchesFactory class from the framework. Have a look in Reflector to find all classes that derive from IActivityTemplateFactory to get some ideas as to what the inbuilt factories do.

When you compile up your project you’ll find the ‘Dropper’ activity on the toolbox, and when you drag & drop an instance of this activity you’ll get a Pick with two branches. Sorted.

Well, sort of.

I mentioned at the start of the article that I’d show how to drop not only a bunch of related activities, but also something that doesn’t derive from the Activity class. Your first thought might be to change the Create method and return (for example) a PickBanch, however there’s a problem. The return type is defined as Activity, so using this method to add non-Activity derived classes isn’t going to work.

Stage 2 – Adding non-Activity classes to the toolbox

If you are hosting the Workflow Designer yourself then this is as easy as adding anything else to the toolbox – you simply get hold of the ToolboxControl and add a new tool to it…

private void InitializeToolbox()
{
    ToolboxControl toolbox = new ToolboxControl();
    ToolboxCategory cat = new ToolboxCategory("Activities");
    cat.Tools.Add(new ToolboxItemWrapper(typeof(Sequence), "Sequence"));
    cat.Tools.Add(new ToolboxItemWrapper(typeof(If), "If/Else"));
    cat.Tools.Add(new ToolboxItemWrapper(typeof(Assign), "Assign"));
    cat.Tools.Add(new ToolboxItemWrapper(typeof(Message), "MessageBox"));
    cat.Tools.Add(new ToolboxItemWrapper(typeof(Pick), "Pick"));
    cat.Tools.Add(new ToolboxItemWrapper(typeof(PickBranch), "PickBranch"));
    toolbox.Categories.Add(cat);

    this.SetValue(ref _toolbox, toolbox, "Toolbox");
}

Here I’ve added a bunch of activities and also a PickBranch (which isn’t an Activity) to my toolbox. Simple.

The problem comes however when you want to do this within Visual Studio. The Workflow folks have very nicely integrated any custom activities into the toolbox so they show up as if by magic, but in order to get something onto the toolbox that isn’t an Activity you have to do a bit more work.

Stage 3 – Adding non-Activity classes to the toolbox in Visual Studio

There are currently (as far as I know!) two ways to do this. One is somewhat more involved than the other so I’ll present the easier of the two here. The first way is to create a Visual Studio Extensibility project which, when registered with Visual Studio, adds new items to the toolbox. The code for this is a bit on the gnarly side and there’s already an example of this available online (see the State Machine activity pack available on codeplex) so instead I’ll do the cheap & cheerful approach.

In the second case what you can do is update the toolbox in Visual Studio from within the activity designer code itself. The trick (if you can call it that) in this instance is to add code to your activity designer that updates the toolbox when your main activity is added to the designer. There’s a nice managed interface that you can use from within your code which is IActivityToolboxService.

What you need to do here is create an activity, add a designer to it, and within the designer you can then hook events (in particular the addition of the activity to the design surface), and at this point you can then add your other items to the toolbox.

In my example I’ve create a DayScheduler activity, which when dropped onto the design surface constructs two branches for you as I’ve also implemented IActivityTemplateFactory to construct these brnaches and add them as well…

The activity contains a number of branches similar to the Parallel activity – indeed I modelled most of the code on that activity as mine is very similar. When you drop the DayScheduler onto the designer it constructs two braches which are instances of the DaySchedulerBranch class. This class isn’t an activity – it’s simply a class derived from Object (in the same way as ParallelBranch is).

There' are two mandatory properties on the DayScheduleBranch – Action (an Activity) and ScheduleDays (an enum). This second property defines which day of the week the child activity will be scheduled – so the DayScheduler will execute children (pun intended) based on the current day of the week. In the example code when I add a DayScheduler activity I construct two branches – one that executes on weekdays only and another that executes on weekends only. You can add in any number of branches and select which days the child activities execute on. I defined an enum for this containing individual weekdays, and used the [Flags] attribute to also include all weekdays and both weekend days to make your life easier when selecting which day(s) your child activities should run.

The main point of the code is to show how, within Visual Studio, you can add non-Activity classes to the toolbox. This is done within the designer for the DayScheduler activity and the main parts of this designer class are shown below…

/// <summary>
/// This designer updates the toolbox to add in a new tool as necessary
/// </summary>
public partial class DaySchedulerDesigner
{
    public DaySchedulerDesigner()
    {
        InitializeComponent();

        // Use the same cateory name as the assembly
        _category = this.GetType().Assembly.GetName().Name;
    }

    /// <summary>
    /// Hook the property change notification
    /// </summary>
    /// <param name="newItem"></param>
    protected override void OnModelItemChanged(object newItem)
    {
        base.OnModelItemChanged(newItem);

        if (null == _toolbox)
            _toolbox = this.Context.Services.GetService<IActivityToolboxService>();

        AddToolboxItem();
    }

    /// <summary>
    /// Add the tool to the toolbox
    /// </summary>
    private void AddToolboxItem()
    {
        bool exists = _toolbox.EnumCategories().Contains(_category);

        if (!exists)
            _toolbox.AddCategory(_category);

        string _toolName = typeof(DaySchedulerBranch).AssemblyQualifiedName;
        bool toolExists = _toolbox.EnumItems(_category).Contains(_toolName);

        if (!toolExists)
        {
            _toolbox.AddItem(_toolName, _category);
        }
    }

    /// <summary>
    /// Stores a link to the toolbox
    /// </summary>
    private IActivityToolboxService _toolbox;

    /// <summary>
    /// Defines the category that this tool is added to
    /// </summary>
    private string _category;
}

The code overrides the OnModelItemChanged method which calls AddToolboxItem(). OnModelItemChanged is called when you drop the DayScheduler activity onto the designer, and here I obtain a reference to the IActivityToolboxService interface which is used to add/enumerat and delete items from the toolbox.

Within AddToolboxItem I then check if the category and tool have already been defined, and if not simply call the relevant methods to add the tool to the toolbox.

So, within Visual studio you’ll initially see just the DayScheduler activity within the toolbox, however once you’ve dropped an instance of this onto the designer you’ll then see the following in the toolbox…

You can then of course use this to drop an instance of the branch activity onto the design surface. Voila!

The Download

I’ve create a VS2010 project that includes all of the code for you to look at. Please download from here. If the code works it was written by me, if not I don’t know who wrote it.

Visual Studio has had the concept of designers from the first version of the framework, and this method uses the [Designer] attribute. To associate a designer with an activity you could write the following code…

[Designer(typeof(CustomWriteLineDesigner))]
public class CustomWriteLine : CodeActivity
{
    protected override void Execute(CodeActivityContext context)
    {
        // Your code here...
    }
}

Here the [Designer] attribute is using typeof to associate the designer class with the activity. The problem here is that there’s a hard-link between the activity class and its designer – usually you would create a designer in a separate assembly so that at runtime you would not need to load up the assembly that contains the designer(s).

In order to provide a soft-link you can use another override of the [Designer] attribute which takes a fully qualified type-name as in the following…

[Designer("CustomActivities.Designers.CustomWriteLineDesigner, CustomActivities.Designers")]
public class CustomWriteLine : CodeActivity
{
    protected override void Execute(CodeActivityContext context)
    {
        // Your code here...
    }
}

This ensures that the activity assembly doesn’t need to add a reference to the designers assembly so all is good. Well, sort of.

The problem with the above is that the designer is more or less hard-coded, and if you wished to add a different designer you would have a hard job doing this.

The new way

If you look at any of the standard activities that come with Workflow 4 you’ll notice a distinct absence of any [Designer] attributes, so how does Visual Studio find the right designer? With WF 4 we now support the concept of registering a designer in another class – as in all things, every problem in computing can be solved by adding another level of indirection.

In this case it’s the IRegisterMetadata interface which is defined in the System.Activities.Presentation.Metadata namespace. This interface has one simple method – Register() which is called by Visual Studio under certain circumstances in order to register the designer (and indeed any other attributes) for your activity.

If you use Reflector you’ll find several classes that derive from this interface and they’re typically called "DesignerMetadata”. If you’re hosting the WF designer yourself you need to add in the following call to ensure that the designers are registered for all standard activities…

new DesignerMetadata().Register();

Internally the method constructs an instance of the AttributeTableBuilder class, constructs a number of custom attributes, adds these to the builder and then calls AddAttributeTable on the MetadataStore class…

public class DesignerMetadata : IRegisterMetadata
{
    public void Register()
    {
        AttributeTableBuilder builder = new AttributeTableBuilder();

        builder.AddCustomAttributes(typeof(CustomWriteLine), 
            new DesignerAttribute(typeof(CustomWriteLineDesigner)));

        MetadataStore.AddAttributeTable(builder.CreateTable());
    }
}

In effect this code is simply using the TypeDescriptor class to add on a custom type provider, which is then used by the designer to find the [Designer] attribute (and possibly others) for any object added to the design surface. So, rather than have a hard reference from the Activity to its designer class, now we’re using an indirect method to register the designer. We’re still using the same attribute, but applying it in a separate assembly.

The nice thing here is that it allows you to completely change the look and feel of the standard activities as you can add in your own designer for any of them. Instead of calling DesignerMetadata.Register you can do the job yourself, and replace any standard designers with your own. I’d urge caution here – you might end up writing a load of designer code but it’s there if you wish to use it.

Integration with Visual Studio

Having gone to all the bother of creating your own class that derives from IRegisterMetadata, how do you tell Visual Studio to use this?

In this instance you need to do two things (and both are very important)…

• If your creating CustomActivities.dll, create another assembly called CustomActivities.Design.dll
• Make sure that both assemblies reside in the same directory

The last point may well trip you up – especially if you’re developing both assemblies in the same solution and you want the registration to update as you’re working. Even if you’re test project contains a reference to both dll’s the designer won’t update on the user interface in Visual Studio *unless* both assemblies build to the same directory (or rather, the *.Design.dll assembly builds to the same directory as the activity assembly).

The best way to ensure that the second point is sorted is to update the properties for the design assembly in Visual Studio and change the output path to be the same directory as your activity assembly…

Make sure you alter the output path for both the Debug and Release builds. And I love writing documentation so I always provide a documentation file to go along with my code. Yes – seriously!

One more tweak

There’s one more thing you can do to alter the design time behaviour of your activities and that’s to create another assembly that contains designers, but this time you’ll call it CustomActivities.VisualStudio.Design.dll.

If Visual Studio finds this assembly it will use this in addition to the .Design.dll. So, you could have one designer for mere mortals and another for developers. Maybe there are some properties that you only want developers to access – one example might be you wish to provide developers with an expression text box to define the value for an argument, but provide just a regular text box to less sophisticated users.

You can download a sample project from http://www.morganskinner.com/stuff/designtimeactivities.zip which shows off the above. Change from a Debug/Release build to the Developer build and then reload the Workflow1.xaml file to see a different designer.