Suspending a WF Program Instance

A running WF program instance can be suspended by calling the Suspend method of the WorkflowInstance class. A running WF program instance will also be suspended if a SuspendActivity within the WF program is executed. Suspend-Activity is defined in the System.Workflow.ComponentModel namespace and is shown in Listing 5.15.

Listing 5.15. `SuspendActivity`

namespace System.Workflow.ComponentModel
{
  public sealed class SuspendActivity : Activity
  {
    public string Error { get; set; }

    /* *** other members *** */
  }
}

Use of SuspendActivity in XAML looks like this:

<wf:SuspendActivity x:Name="s1" Error="Please fix xyz" />

A suspended WF program instance is not allowed to proceed further in its execution, even if there is work enqueued in its scheduler work queue. The instance remains in a suspended state until the Resume method of its WorkflowInstance is called. The Error property of SuspendActivity (and the equivalent string parameter of the Suspend method of WorkflowInstance ) can be used to convey information about why the instance has been suspended.

The WorkflowRuntime has a WorkflowSuspended event, which is raised whenever a WF program instance is suspended. Listing 5.16 illustrates this process.

Listing 5.16. WF Program Instance Suspension

static void Main()
{
  WorkflowRuntime runtime = new WorkflowRuntime();
  runtime.StartRuntime();

runtime.WorkflowSuspended += delegate(object sender,


WorkflowSuspendedEventArgs e)

{
    Console.WriteLine("Instance suspended: " +
      e.WorkflowInstance.InstanceId);
    Console.WriteLine("Reason: " + e.Error);
  };

  WorkflowInstance instance = ...
  instance.Suspend("Need to suspend it");

  ...
}

WorkflowInstance.Suspend stops the execution of the WF program instance, and also causes the WorkflowRuntime to raise the WorkflowSuspended event. The suspended WF program instance remains in memory; if a host application wishes to unload the instance, the Unload method can be called as well (for example, from within the handler of the WorkflowSuspended event). A WF program instance that has been suspended must always be explicitly resumed in order for its execution to continue; it is not enough to simply load a suspended instance that was previously unloaded.

Calling Resume on WorkflowInstance will resume the program's execution from wherever it had left off. Calling Resume has no effect in causing the program execution to move forward if there are no items in the WF scheduler's work queue; it only removes a barrier to execution by moving the instance out of the suspended state.

Terminating a WF Program Instance

A WF program instance can be terminated by calling the Terminate method of the WorkflowInstance class. A WF program instance will also be terminated if an exception in the program propagates to the root activity and is not handled, or if a TerminateActivity within the WF program is executed. The TerminateActivity class is defined in the System.Workflow.ComponentModel namespace and is shown in Listing 5.17.

Listing 5.17. `TerminateActivity`

namespace System.Workflow.ComponentModel
{
  public sealed class TerminateActivity : Activity
  {
    public string Error { get; set; }

    /* *** other members *** */
  }
}

Use of TerminateActivity in XAML looks like this:

<wf:TerminateActivity x:Name="t1" Error="Cannot proceed" />

The WorkflowRuntime has a WorkflowTerminated event, which is raised whenever a WF program instance is terminated. Termination of a WF program instance is considered abnormal completion. Thus, the WorkflowTerminatedEventArgs that carries the data for the WorkflowTerminated event contains one property of type Exception . This exception is either an unhandled exception that occurred within the instance or, if the Terminate method of WorkflowInstance was called by the host application (or a TerminateActivity within the WF program executed) a special WorkflowTerminatedException , which carries the error string that was reported as part of the termination.

Listing 5.18 shows the WorkflowTerminatedEventArgs type.

Listing 5.18. `WorkflowTerminatedEventArgs`

namespace System.Workflow.Runtime
{
  public class WorkflowTerminatedEventArgs : WorkflowEventArgs
  {
    public Exception Exception { get; }
  }
}

Calling WorkflowInstance.Terminate causes the execution of the program instance to end immediately. As part of termination, the WF program instance is persisted and removed from memory. Although a WF program instance is persisted as part of termination, its execution can never be continued . The instance has irrevocably transitioned to the Terminated state. Instance termination is illustrated in Listing 5.19.

Listing 5.19. WF Program Instance Termination

static void Main()
{
    using(WorkflowRuntime runtime = new WorkflowRuntime())
  {
    runtime.StartRuntime();

runtime.WorkflowTerminated += delegate(


object sender, WorkflowTerminatedEventArgs e)

{
      Console.WriteLine("Instance terminated: " +
        e.WorkflowInstance.InstanceId);
      Console.WriteLine("Exception message: " +
        e.Exception.Message);
    };

    WorkflowInstance instance = ...
    instance.Terminate("Need to terminate it");

    ...
  }
}

Buy on amazon.com >>

Shukla D., Schmidt B.

<< Previous page

Table of contents

Next page >>