WorkflowInstance.EnqueueItem Method (IComparable, Object, IPendingWork, Object)

 
System_CAPS_noteNote

The .NET API Reference documentation has a new home. Visit the .NET API Browser on docs.microsoft.com to see the new experience.

Posts a message to the specified workflow queue synchronously.

Namespace:   System.Workflow.Runtime
Assembly:  System.Workflow.Runtime (in System.Workflow.Runtime.dll)

public void EnqueueItem(
	IComparable queueName,
	object item,
	IPendingWork pendingWork,
	object workItem
)

Parameters

queueName
Type: System.IComparable

The name of the WorkflowQueue.

item
Type: System.Object

The object to enqueue.

pendingWork
Type: System.Workflow.Runtime.IPendingWork

An IPendingWork that allows the sender to be notified when item is delivered.

workItem
Type: System.Object

An object to be passed to the IPendingWork methods.

Exception Condition
ArgumentNullException

queueName is a null reference (Nothing in Visual Basic).

InvalidOperationException

The workflow runtime engine is not running.

-or-

The WorkflowQueue specified by queueName does not exist.

-or-

The WorkflowQueue specified by queueName is not enabled.

Sends the item to the specified WorkflowQueue. If you want to be notified when the message is delivered, you can implement IPendingWork in your service and pass a workItem and an IPendingWork object to EnqueueItem. If you do not want such notification, you can pass a null reference (Nothing in Visual Basic) for pendingWork and workItem.

When using this method with a state machine workflow, you might get an exception with the message "Queue '{0}' is not enabled." This happens when the current state of the state machine does not know how to handle a specific event. For example, when some state other than the current state contains the EventDrivenActivity that contains the HandleExternalEventActivity that is represented by the queue '{0}'.

System_CAPS_noteNote

Messages are not guaranteed to be received by the workflow instance in the order that they were sent. For example, if receiving a message in an existing queue (Queue A) causes a workflow to create another queue (Queue B), which then listens for another message sent after the first message, it is possible that the second message will arrive first, and will not be received due to its queue not being created yet. To prevent this issue, the second message should not be sent until the presence of the second queue is verified (using GetWorkflowQueueData.)

The following code example demonstrates how to use EnqueueItem. When the WorkflowIdled event occurs, the OnWorkflowIdled method defined in this example is called. It determines which workflow is idled using the WorkflowInstance property and then gets a collection of queued items for the workflow instance by calling the GetWorkflowQueueData method. The code iterates over the collection to determine which activity is waiting for the event that idled the workflow. It then sends an exception to the workflow queue using the EnqueueItem method along with the name of the event queue item.

This code example is part of the Canceling a Workflow SDK sample from the Program.cs file. For more information, see Canceling a Workflow.

static void OnWorkflowIdled(object sender, WorkflowEventArgs e)
{
    WorkflowInstance workflow = e.WorkflowInstance;

    Console.WriteLine("\n...waiting for 3 seconds... \n");
    Thread.Sleep(3000);

    // what activity is blocking the workflow
    ReadOnlyCollection<WorkflowQueueInfo> wqi = workflow.GetWorkflowQueueData();
    foreach (WorkflowQueueInfo q in wqi)
    {
        EventQueueName eq = q.QueueName as EventQueueName;
        if (eq != null)
        {
            // get activity that is waiting for event
            ReadOnlyCollection<string> blockedActivity = q.SubscribedActivityNames;
            Console.WriteLine("Host: Workflow is blocked on " + blockedActivity[0]);

            // this event is never going to arrive eg. employee left the company
            // lets send an exception to this queue
            // it will either be handled by exception handler that was modeled in workflow
            // or the runtime will unwind running compensation handlers and exit the workflow
            Console.WriteLine("Host: This event is not going to arrive");
            Console.WriteLine("Host: Cancel workflow with unhandled exception");
            workflow.EnqueueItem(q.QueueName, new Exception("ExitWorkflowException"), null, null);
        }
    }
}

.NET Framework
Available since 3.0
Return to top
Show: