I wrote the following for the Using CSLA .NET 3.0 ebook, but I don't think I'm going to use it now, because I've wrapped most of this into a new class in CSLA .NET. Rather than letting this go to waste though, I thought I'd post it here. Remember that it is just draft content, so it may have typos or errors, but perhaps it will be useful to someone:
Basic Workflow Execution
Executing a workflow is a little tricky, because workflows default to running on a background thread. That means you must take steps to ensure that the workflow completes before the host process terminates.
One way to solve this issue is to always execute a workflow synchronously. Another is to use a thread synchronization object to prevent the process from terminating until the workflow completes.
Note: It is also possible to suspend and resume workflows, and even to unload them from memory so they store their state in a database. Later you can reload that workflow instance and resume it. These advanced scenarios are outside the scope of this book
Synchronous Execution
The code to synchronously execute a workflow follows a standard pattern:
1. Create an instance of the WorkflowRuntime.
2. Create a synchronization object.
3. Set up event handlers.
4. Create workflow instance.
5. Ensure you have a valid principal object.
6. Start the workflow.
7. Wait for the workflow to complete.
The only step unique to CSLA .NET is number 5, and that is only required if you are using custom authentication. The WF runtime will automatically ensure that the background thread that executes the workflow has the same principal as the thread that calls the workflow’s Start() method, but you must ensure that the principal is set on the current thread before calling Start().
The following code implements these steps to execute the ProjectWorkflow implemented earlier in this chapter:
using (WorkflowRuntime workflowRuntime = new WorkflowRuntime())
{
Exeception error = null;
AutoResetEvent waitHandle = new AutoResetEvent(false);
workflowRuntime.WorkflowCompleted +=
delegate(object sender, WorkflowCompletedEventArgs e)
{
waitHandle.Set();
};
workflowRuntime.WorkflowTerminated +=
delegate(object sender, WorkflowTerminatedEventArgs e)
{
error = e.Exception;
waitHandle.Set();
};
// create workflow instance
Dictionary<string,object> parameters = new Dictionary<string,object>();
parameters.Add("ProjectId", projectId);
WorkflowInstance instance =
workflowRuntime.CreateWorkflow(
typeof(PTWorkflow.ProjectWorkflow),
parameters);
// login before starting WF instance
ProjectTracker.Library.Security.PTPrincipal.Login("pm", "pm");
// execute workflow
instance.Start();
// wait for workflow to complete
waitHandle.WaitOne();
// throw any workflow exception
if (error != null)
throw error;
Creating the workflow instance involves setting up a Dictionary<string, object> that contains name/value pairs for any parameters to be passed into th workflow instance:
// create workflow instance
Dictionary<string,object> parameters = new Dictionary<string,object>();
parameters.Add("ProjectId", projectId);
WorkflowInstance instance =
workflowRuntime.CreateWorkflow(
typeof(PTWorkflow.ProjectWorkflow),
The name in the dictionary must correspond to the name of a dependency property defined by the workflow, and of course the type of the value must match the dependency property type.
Keep in mind that creating an instance of a workflow does not start the workflow. The workflow won’t start executing until the Start() method is called later in the code.
The waitHandle synchronization object is the key to making this process synchronous. The waitHandle object starts out unset because false is passed to its constructor as its initial state:
AutoResetEvent waitHandle = new AutoResetEvent(false);
At the bottom of the code is a line that calls WaitOne(), thus blocking the current thread until waitHandle is set:
instance.Start();
// wait for workflow to complete
While the current (starting) thread is blocked, the workflow is busy executing on a background thread. In other words, the Start() call returns immediately, having just started the workflow instance executing on a background thread. Without the WaitOne() call, the current thread would exit the code block, which would dispose the WF engine instance while it is executing the workflow. The result would be an exception.
Notice how the event handlers for the WorkflowCompleted and WorkflowTerminated events both call waitHandle.Set(). These events are raised by the WF engine when the workflow either completes or terminates unexpectedly. Either way, by calling the Set() method, the current thread is released so it can continue running.
In the case of a workflow terminating unexpectedly, the exception from the workflow is made available to the WorkflowTerminated event handler. You can choose what to do with this information as appropriate for your application. One technique is shown here, which is to store the Exception object in a field:
delegate(object sender, WorkflowTerminatedEventArgs e)
{
error = e.Exception;
waitHandle.Set();
And then have the current thread throw the exception once it is unblocked:
// wait for workflow to complete
waitHandle.WaitOne();
// throw any workflow exception
if (error != null)
The result of this code is that the workflow appears to run synchronously, even though it really executes on a background thread.
Asynchronous Execution
Allowing a workflow to run asynchronously is just a slightly more complex version of running the workflow synchronously. The important thing is to ensure that your process doesn’t exit until the workflow is complete. This means that the synchronization object must be available at a broader scope so you can write code to prevent the application from closing if the workflow is still running.
You also must come up with a way to deal with any exception object in the case that the workflow terminates unexpectedly. One solution is to elevate the error field from the previous example to a broader scope as well.
Finally, the WorkflowRuntime instance must remain in memory until the workflow completes.
This means that you must define these fields so they exist at an application level, for instance using static fields:
private static AutoResetEvent _waitHandle = null;
private static Exception _workflowError = null;
private static WorkflowRuntime _workflowRuntime = null;
Then you can create a method to start the workflow:
public static void BeginWorkflow(Guid projectId)
{
_workflowRuntime = new WorkflowRuntime();
_waitHandle = new AutoResetEvent(false);
_workflowRuntime.WorkflowCompleted +=
delegate(object sender, WorkflowCompletedEventArgs e)
{
_waitHandle.Set();
};
_workflowRuntime.WorkflowTerminated +=
delegate(object sender, WorkflowTerminatedEventArgs e)
{
_workflowError = e.Exception;
_waitHandle.Set();
};
// create workflow instance
Dictionary<string,object> parameters = new Dictionary<string,object>();
parameters.Add("ProjectId", projectId);
WorkflowInstance instance =
_workflowRuntime.CreateWorkflow(
typeof(PTWorkflow.ProjectWorkflow),
parameters);
// login before starting WF instance
ProjectTracker.Library.Security.PTPrincipal.Login("pm", "pm");
// execute workflow
instance.Start();
Notice that the WorkflowRuntime object is no longer in a using block, so it can remain in memory, not disposed, while the workflow instance is running on the background thread.
The workflow instance is created the same as before, and its Start() method is called. At that point this method simply ends, returning to the caller.
Once you call BeginWorkflow() the workflow is started on a background thread, but your current thread (often the UI thread) is free to continue working.
The final piece to the puzzle is a method your application can call before it exits, or when it otherwise can’t continue without the workflow having completed:
public static void EndWorkflow()
{
// wait for workflow to complete
_waitHandle.WaitOne();
// dispose runtime
_workflowRuntime.Dispose();
if (_workflowError != null)
throw _workflowError;
It is important to realize that this method will block the current thread until _waitHandle is set. If the workflow completes before this method is called, then _waitHandle is already set, and this method runs immediately, but if the workflow is still running, this method will block until the workflow completes or terminates.
For this to work, you must call EndWorkflow() before your process terminates to properly dispose the runtime and to determine if the workflow terminated unexpectedly.