WorkflowInstance.EnqueueItemOnIdle Method

Definition

Namespace:

System.Workflow.Runtime

Assembly:

System.Workflow.Runtime.dll

Posts a message to the specified workflow queue when the workflow is idle. EnqueueItemOnIdle(IComparable, Object, IPendingWork, Object) waits until the workflow reaches an idle point and enqueues after verifying that the workflow scheduler is idle (that is, no active operation is being executed).

public:
 void EnqueueItemOnIdle(IComparable ^ queueName, System::Object ^ item, System::Workflow::Runtime::IPendingWork ^ pendingWork, System::Object ^ workItem);

public void EnqueueItemOnIdle (IComparable queueName, object item, System.Workflow.Runtime.IPendingWork pendingWork, object workItem);

member this.EnqueueItemOnIdle : IComparable * obj * System.Workflow.Runtime.IPendingWork * obj -> unit

Public Sub EnqueueItemOnIdle (queueName As IComparable, item As Object, pendingWork As IPendingWork, workItem As Object)

Parameters

queueName

IComparable

The name of the WorkflowQueue.

item

Object

The object to enqueue.

pendingWork

IPendingWork

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

workItem

Object

An object to be passed to the IPendingWork methods.

Exceptions

ArgumentNullException

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

InvalidOperationException

The workflow runtime engine is not running.

-or-

The workflow instance is suspended.

-or-

The WorkflowQueue specified by queueName does not exist.

-or-

The WorkflowQueue specified by queueName is not enabled.

Examples

The following example demonstrates sending information to a workflow instance using the EnqueueItemOnIdle method. First, a WorkflowInstance object is created and started; next, an object that implements the IPendingWork interface is created. EnqueueItemOnIdle is then called, passing in string values for the queue name, the enqueued item, and the work item to be passed to the methods of the pendingWork object.

// Create a workflow runtime environment
WorkflowRuntime workflowRuntime = new WorkflowRuntime();
// Create a new instance of the out-of-box SqlWorkflowPersistenceService.
// Use the non-locking constructor, since we're only creating a single Workflow Runtime.
NameValueCollection parameters = new NameValueCollection();
parameters.Add("ConnectionString",
    "Initial Catalog=SqlPersistenceService;Data Source=localhost;Integrated Security=SSPI;");
//Set UnloadOnIdle to true, so that the service will persist the workflow
parameters.Add("UnloadOnIdle", "true");
SqlWorkflowPersistenceService persistenceService =
   new SqlWorkflowPersistenceService(parameters);

// Add the service to the runtime
workflowRuntime.AddService(persistenceService);
// Create a WorkflowInstance object
WorkflowInstance workflowInstance = workflowRuntime.CreateWorkflow(typeof(Workflow1));
// Start the instance
workflowInstance.Start();
// Create an instance of a class that implements IPendingWork for notification
PendingService pendingWork = new PendingService();
// Send the workflow the message
workflowInstance.EnqueueItemOnIdle("ActionQueue", "StartWork", pendingWork, "ActionItem");

' Create a workflow runtime environment
Dim workflowRuntime As New WorkflowRuntime()
' Create a new instance of the out-of-box SqlWorkflowPersistenceService.
' Use the non-locking constructor, since we're only creating a single Workflow Runtime.
Dim parameters As New NameValueCollection()
parameters.Add("ConnectionString", _
    "Initial Catalog=SqlPersistenceServiceData Source=localhostIntegrated Security=SSPI")
'Set UnloadOnIdle to true, so that the service will persist the workflow
parameters.Add("UnloadOnIdle", "true")
Dim persistenceService As _
   New SqlWorkflowPersistenceService(parameters)

' Add the service to the runtime
workflowRuntime.AddService(persistenceService)
' Create a WorkflowInstance object
Dim workflowInstance As WorkflowInstance = workflowRuntime.CreateWorkflow(GetType(Workflow1))
' Start the instance
workflowInstance.Start()
' Create an instance of a class that implements IPendingWork for notification
Dim pendingWork As New PendingService()
' Send the workflow the message
workflowInstance.EnqueueItemOnIdle("ActionQueue", "StartWork", pendingWork, "ActionItem")

Remarks

Waits for the workflow instance to become idle and then sends the item to the specified WorkflowQueue. If you call EnqueueItemOnIdle while the workflow instance is suspended, the workflow runtime engine will throw an InvalidOperationException. 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 you are using this method with a state machine workflow, you might get an exception that contains the message "Queue '{0}' is not enabled." This occurs 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}'.