Workflow Control Endpoint

This topic applies to Windows Workflow Foundation 4 (WF4).

The workflow control endpoint allows developers to call control operations to remotely control workflow instances hosted using WorkflowServiceHost. This feature can be used to programmatically perform control operations like suspend, resume, and terminate.

Caution:
If using the workflow control endpoint within a transaction and the workflow being controlled contains a Persist activity, the workflow instance will hang until the transaction times out.

Workflow Instance Management

.NET Framework version 4 defines a new contract called IWorkflowInstanceManagement. This contract defines a series of control operations that allow you remotely control workflow instances hosted by WorkflowServiceHost. WorkflowControlEndpoint is a standard endpoint that provides an implementation of the IWorkflowInstanceManagement contract. WorkflowControlClient is a class that is used to send the control operations to the WorkflowControlEndpoint. The default binding for WorkflowControlEndpoint is NetNamedPipeBinding.

Workflow instances can be in one of the following states:

• Active
  The state of a workflow instance before it reaches the completed state and when it is not in the suspended state. While in this state, the workflow instance runs and processes application messages.

• Suspended
  While in this state, the workflow instance does not run even if there are activities that have not started running or have partially run.

• Completed
  The final state of a workflow instance. The workflow instance cannot run after reaching the completed state.

IWorkflowInstanceManagement

The IWorkflowInstanceManagement interface defines a set of control operations with synchronous and asynchronous versions. The transacted versions require use of a transaction-aware binding. The following table lists the control operations supported.

Control Operation	Description
Abort	Forcefully stops the execution of the workflow instance.
Cancel	Transitions a workflow instance from the active or suspended state to the completed state.
Run	Provides a workflow instance the opportunity to execute.
Suspend	Transitions a workflow instance from the active state to the suspended state.
Terminate	Transitions a workflow instance from the active or suspended state to the completed state.
Unsuspend	Transitions a workflow instance from the suspended state to the active state.
TransactedCancel	Performs the Cancel operation under a transaction (flowed in from the client or created locally). If the system maintains the durable state of the workflow instance, the workflow instance must be persisted during execution of this operation.
TransactedRun	Performs the Run operation under a transaction (flowed in from the client or created locally). If the system maintains the durable state of the workflow instance, the workflow instance must be persisted during execution of this operation.
TransactedSuspend	Performs the Suspend operation under a transaction (flowed in from the client or created locally). If the system maintains the durable state of the workflow instance, the workflow instance must be persisted during execution of this operation.
TransactedTerminate	Performs the Terminate operation under a transaction (flowed in from the client or created locally). If the system maintains the durable state of the workflow instance, the workflow instance must be persisted during execution of this operation.
TransactedUnsuspend	Performs the Unsuspend operation under a transaction (flowed in from the client or created locally). If the system maintains the durable state of the workflow instance, the workflow instance must be persisted during execution of this operation.

The IWorkflowInstanceManagement contract does not provide a means to create a new workflow instance, only to manage existing workflow instances. For more information about remotely creating a new workflow instance, see Workflow Service Host Extensibility.

WorkflowControlEndpoint

WorkflowControlEndpoint is a standard endpoint with a fixed contract, IWorkflowInstanceManagement. When added to a WorkflowServiceHost instance, this endpoint can then be used to send command operations to any workflow instance hosted by the host instance. For more information about standard endpoints, see Standard Endpoints.

WorkflowControlClient

WorkflowControlClient is a class that allows you to send control messages to a WorkflowControlEndpoint on a WorkflowServiceHost. It contains a method for each of the operations supported by the IWorkflowInstanceManagement contract except for the transacted operations. WorkflowControlClient uses the ambient transaction to determine whether a transacted operation should be used.