Jason Prickett's Blog : Workflow

WF - Creating an Activity Base Class

Jason Prickett — Wed, 23 Apr 2008 20:58:44 GMT

(or Designing Your Workflow Activity Class Hierarchy)

One of the questions that we've had to consider when designing our Workflow Activity Class Hierarchy is whether it is valuable to have our own Activity base class (derived from Activity and inherited by all of our activity classes).

Our answer was "Yes". We decided that there were several good reasons to create our own Activity base class. Here are the reasons and some explanation.

Implement the Asynchronous Activity pattern for all our activities - I described this pattern and the reasons that you want to do this in a previous post. Basically, the idea is that we want all our activities to do their work on a background thread so that they are cancelable.
Shared properties - there were a few properties that we felt like we wanted on all our activities. I won't get into the specifics of them, but this is a reason to create any base class.
Common tracking and logging - we wrote a little bit of code associated with Activity tracking and logging information about the workflow. We wanted to be consistent in the way that we logged about activities starting and stopping, so we put this code into the base class. We even have some generic code that logs all the Properties for our activities using the property collection that is inherited from the actual Activity class.

Our base activity class gives us all this but here's the rub...

There are actually two Workflow Activity base classes. If you want to create a Composite activity (one that contains other activities), you have to derive that class from CompositeActivity instead of Activity. This is extremely unfortunate for us, because there were several activities that we wanted to create that were composite activities. But this means that they couldn't derive from our other base class. So, we had to re-implement some of the base classes functionality in our Composite activity class. This is why when I am designing a tree structure, I try not to make a separate base class for the tree nodes and the leaf nodes. Because, it screws up inheritance, polymorphism and a few other fancy OO words I can't recall.

Keep this gotcha in mind when you start planning your Activity class hierarchy!

WF - The Asynchronous Activity/Service Pattern

Jason Prickett — Fri, 25 Jan 2008 19:14:44 GMT

In my previous blog post (Creating an Asynchronous Workflow Activity), I explained why your custom activities should either be really fast or run asynchronously. But, I didn't give you a real world example of how to do this. In this post I provide an example of the pattern that my team uses when creating a custom activity.

Pattern:

1) Create a service that actually does the work

2) Create a custom activity that uses the service and has a Queue listener event handler to get a message back from the service when the work is done.

Instead of walking you through this one, I just want to present you with the code, commented as much as I could :)

    public class DoSomethingAsyncService : WorkflowRuntimeService
    {
        private Random m_random;

        public DoSomethingAsyncService()
        {
            m_random = new Random();
        }

        public void DoSomethingAsync(Guid instanceId, Guid queueId)
        {
            ThreadPool.QueueUserWorkItem(delegate(Object state)
                {
                    // Fake a call to a WebService (let's say it takes 10 seconds)
                    Console.WriteLine("Making webservice call.");
                    Thread.Sleep(10000);

                    // Create the QueueItem
                    QueueItem item = new QueueItem();
                    item.ReturnCode = m_random.Next(0, 10);
                    item.Message = String.Format("The return code is {0}.", item.ReturnCode);

                    try
                    {
                        // Now send this item to the appropriate queue
                        WorkflowInstance instance = Runtime.GetWorkflow(instanceId);
                        instance.EnqueueItem(queueId, item, null, null);
                    }
                    catch (InvalidOperationException)
                    {
                        // Catch any InvalidOperationExceptions that occur due to the 
                        // workflow having already completed, etc.
                    }
                });
        }
    }

    public class QueueItem
    {
        public int ReturnCode;
        public String Message;
    }

    public class DoSomethingAsyncActivity : Activity
    {
        private Guid m_queueId;

        protected override ActivityExecutionStatus Execute(ActivityExecutionContext executionContext)
        {
            // Create my queue
            m_queueId = Guid.NewGuid();
            WorkflowQueuingService queuingService = (WorkflowQueuingService)executionContext.GetService(typeof(WorkflowQueuingService));
            WorkflowQueue queue = queuingService.CreateWorkflowQueue(m_queueId, true);

            // Hook the item available event. This event will be triggered when our
            // service enqueues an item.
            queue.QueueItemAvailable += new EventHandler<QueueEventArgs>(QueueItemAvailable);

            // Call the service to perform the async work.
            DoSomethingAsyncService service = (DoSomethingAsyncService)executionContext.GetService(typeof(DoSomethingAsyncService));
            service.DoSomethingAsync(WorkflowInstanceId, m_queueId);

            // Return Executing to let the workflow know that we are still working.
            return ActivityExecutionStatus.Executing;
        }

        private void QueueItemAvailable(object sender, QueueEventArgs e)
        {
            // The activity execution context is always passed in as the sender.
            ActivityExecutionContext context = sender as ActivityExecutionContext;

            // Checking for a null context just in case something really strange is happening.
            if (context != null)
            {
                // Get the queue service so we can get the Queue object.
                // Note: you cannot salt away the actual queue object, the Workflow runtime does not allow it.
                WorkflowQueuingService queuingService = context.GetService<WorkflowQueuingService>();

                // Make sure the queue exists before going any further.
                if (queuingService.Exists(m_queueId))
                {
                    WorkflowQueue queue = queuingService.GetWorkflowQueue(m_queueId);

                    // Dequeue the item that was queued by the service.
                    QueueItem item = queue.Dequeue() as QueueItem;
                    if (item != null)
                    {
                        // We only expect one thing to ever be put into our Queue;
                        // so, now we remove the queue.
                        queue.QueueItemAvailable -= QueueItemAvailable;
                        queuingService.DeleteWorkflowQueue(m_queueId);

                        // Finally inspect the results and do something with them.
                        Console.WriteLine(item.Message);

                        // Once we have finished our mission, we close this activity
                        context.CloseActivity();
                        return;
                    }
                }
            }

            // We should not get here if everything works as we expect.
            // So, throw an exception so the workflow will be terminated.
            throw new Exception("Something unexpected was placed in the Queue.");
        }
    }

Try creating a workflow that contains a Parallel activity and add this activity to both branches. If you really want to run activities in parallel, this is how it needs to be done.

Don't forget to add the service to the runtime!

Happy flowing!

WF - Creating an Asynchronous Workflow Activity

Jason Prickett — Fri, 25 Jan 2008 17:57:40 GMT

What a silly topic for a blog post! Workflow already runs my whole activity tree on a another thread, I don't have to worry about being Async, Do I? Yes, you do. While it is true that each Workflow gets its own thread (in the default setup), that thread can be easily blocked by a long running or hung activity. Let's look at an example...

Create a Sequential Workflow Console application in Visual Studio with the following Activity tree:

Sequential Workflow

WhileActivity (set the condition to true so it runs forever)

CodeActivity (the code should just do a Console.WriteLine("Hello World")

So, now go to the Program.cs file or wherever the code is that Starts the workflow instance.

Add a Thead.Sleep(1000) after the instance.Start() call and then an instance.Terminate("kill workflow") to stop the workflow.

When you run the workflow, you should notice that you get a few "Hello World" lines and one "kill workflow" line. Here, terminate works just as you expect it to. But now let's change our workflow so that the while is done in the code activity...

Sequential Workflow

CodeActivity (the code should contain while(true) Console.WriteLine("Hello World"))

When you run the workflow this time, it will never end :(

If you put a break point on the instance.Terminate line, it does get called. So, why doesn't the Workflow terminate? Well, like all other actions that happen in the workflow instance, the terminate action goes through a queue and waits for the background thread to dequeue it and do it. Unfortunately, the queue is only processed in between activities executing. So, the termination request remains in the workflow queue forever in our example.

If you are running complex workflows that may need to actually be stopped in the middle (like we do) then you need to avoid code activities that have loops and start writing asynchronous custom activities. So, how do we write a custom activity so that it is stoppable? The first thing you have to do is create a workflow runtime service that can do the actual work for the activity. This means for every custom activity you need a new custom service or at least a new method on your custom service. Here's a sample service:

    public class HelloWorldService : WorkflowRuntimeService
    {
        public void WriteHelloWorldForeverAsync()
        {
            ThreadPool.QueueUserWorkItem(delegate(Object state)
                {
                    while (true) Console.WriteLine("Hello World");
                });
        }
    }

This service will now do the work for us. But to use it, we need a custom activity. Here's the simplest custom activity you could make:

    public class WriteHelloWorldActivity : Activity
    {
        protected override ActivityExecutionStatus Execute(ActivityExecutionContext executionContext)
        {
            HelloWorldService service = (HelloWorldService)executionContext.GetService(typeof(HelloWorldService));
            service.WriteHelloWorldForeverAsync();
            return ActivityExecutionStatus.Executing;
        }
    }

The key thing to note here is that the activity calls a method on the service that returns immediately after starting its background thread. The activity then returns Executing. This allows the workflow to dequeue items from the queue, but not move on to the next activity. Until this activity returns Closed, the next activity will not start.

Oops! before you try and run this you need to create your service, add it to the runtime and add your custom activity to the workflow. In Program.cs, add the following line right after you create the runtime service:

workflowRuntime.AddService(new HelloWorldService());

Then change the workflow to look like this:

Sequential Workflow

WriteHelloWorldActivity

Now, you can run it and see that Terminate works again! Of course, in a real application you need more code than this, because you have to shut down the background thread when you get terminated, and you need to call back to your activity when the background work is finished! Tune in for my next post, where I will show you a real example of of an activity and service that do it all :)

Stopping a Build -> Cancelling a Workflow

Jason Prickett — Thu, 01 Nov 2007 15:11:00 GMT

This post continues my quest to learn more about Windows Workflow and share that experience with you. It assumes knowledge of Windows Workflow. If you don't understand some of the concepts please take a look at one of the books that I mentioned in my first WF post.

One of the operations that we require is the ability to Stop a Build that is in progress. This corresponds to Terminating a workflow. However, in our investigation of how WF handles Terminate, we discovered that it isn't what we really want. Termination of a workflow does not end the workflow immediately. That's not so bad, but it also doesn't give the workflow a chance to clean up anything (i.e. there are no handlers for termination). So, we looked into Cancellation of a workflow instead of using terminate.

We found that it is really hard to cancel a workflow. First of all there is not a WorkflowInstance.Cancel method. So, if you plan to cancel the workflow from outside the instance, you have a hurdle to jump already. But if your workflow is like ours and you can put your own Activity class at the root, you can leap the hurdle pretty easily. What we did was to have the root activity create a Queue (we called it the cancellation queue) with a well known name (a hard coded Guid). From there it seemed obvious that we could Queue an item to this well known Queue and from within the instance call CancelActivity on the root. But alas, that is not allowed. You can only call CancelActivity on the currently executing activity. Bummer! So, we tried cancelling the executing activity, but that ended up just continuing the execution of the next activity after it which wasn't cancelled. Double Bummer!

So, our final solution was to Throw when we got something in the Queue. Throwing automatically causes all activities to cancel including the active one. It also gives the workflow a place to do any clean up that needs to be done by catching the CancellationException at the top of the workflow.

It wasn't pretty, but we were able to accomplish what we wanted. Here is a summary of the steps that actually worked for us:

In the root level activity (which is our own class derived from one of the WF activities) we create a special Queue just for this situation. The Queue has a constant GUID for the name
From outside the workflow, we get the WorkflowInstance and Enqueue an item into this special Queue.
When an item is enqueued, our activity class Throws a special exception. That causes everything to get cancelled.
Our cancellation handlers can do any clean up.
We have a special fault handler that also catches this special exception and eats it, so that the workflow completes normally.

My Introduction to Windows Workflow Foundation (WF)

Jason Prickett — Tue, 09 Oct 2007 14:59:00 GMT

Team Build is a build workflow tool. It manages how and when builds are performed. Currently (in VS2005 and VS2008), that workflow was written in the language of MSBuild. This allows us a lot of flexibility and power on the machine that runs the build. However, modifying the MS.TF.Build.Targets file that contained the description of the workflow was heavily discouraged and by no means easy. So, how can we make changing the workflow of the build easier. The first step (we believe) is to change the language that the workflow is described in. Windows Workflow is a natural choice. As we look at using Windows Workflow within Team Build, I will attempt to write some useful posts on things that we have discovered or realized. Mostly things that the books don't talk about. This is my first attempt...

First let me tell you about the books that I have read on WF. I read Bruce Bukovics' "Pro WF" first. This is a great starter for a developer wanting to write WF solutions. Bruce covers all of the functionality you would need to know. But, if you want to host WF and allow your users to manipulate the workflow directly, you need more details about how it works. The second and last book that I read on WF was "Essential Windows Workflow Foundation" by Dharma Shukla and Bob Schmidt. The Essentials book is really brief, but explains how WF Activities really work. If you plan on writing your own custom activities, this book is very useful.

So, what did I learn. More importantly, what have I learned that I didn't get from the books. Well the first thing you should know is that you can represent a workflow in many different ways. The workflow is basically a tree of classes derived from Activity. There are two ways to represent the tree in the Visual Studio world: in code; and in XAML (basically XML). Workflow uses the extension XOML, however, to let VS know that its a workflow and not some kind of WPF stuff (more on WPF in another post). Working with code is the most natural way to deal with the Activity tree. In fact, even if you choose to create your workflow in XOML, VS will create a code behind file for you and compile your XOML into a dll.

The first lesson we learned was... If you want to use XOML only and not do any code behind, you must create the XOML yourself or hand edit the XOML created by Visual Studio. When Visual Studio creates the XOML file, it assumes you will compile it. To compile XOML you need a special attribute on the root element in the XOML that tells the compiler to create a class. The attribute is "x:Class". If you create a XOML workflow in Visual Studio and open that XOML in the XML editor or in notepad, this should be the first attribute of the root element.

When you load a workflow in the workflow runtime, there are two ways to do it. Call load with a type, this implies that the XOML or straight code workflow is compiled. Or you can call load with an xml reader, that has the XOML loaded. If you choose the xml reader option and that x:Class attribute is in the XOML, an error will be thrown by the runtime. However, if you try to compile XOML without that attribute, compilation will fail. So, the first choice you have to make in using XOML files is "To compile or not to compile" - that is the question ;)