This documentation is archived and is not being maintained.

Workflow Service Host Extensibility

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

.NET Framework version 4 provides the WorkflowServiceHost class for hosting workflow services. This class is used when you are self-hosting a workflow service in a managed application or a Windows service. This class is also used when hosting a workflow service with Internet Information Services (IIS) or Windows Process Activation Service (WAS). The WorkflowServiceHost class provides extension points that allow you to add custom extensions, change the idle behavior, and host non-service workflows (workflows that do not use messaging activities). For an example of changing the idle behavior, see How To: Control Idle Behavior Through Extensibility.

Workflow Service Host Extensions

The WorkflowServiceHost contains a WorkflowExtensions property of type WorkflowInstanceExtensionManager that provides methods to add extensions to the WorkflowServiceHost. Use the Add method to add an extension for each workflow service instance. The delegate specified is called to create a new extension when a workflow service instance is created or loaded from a persistence store. Use the Add method to add an extension for each workflow service host, one instance of the extension is shared for all workflow service instances.

React to Unhandled Exceptions

The WorkflowUnhandledExceptionBehavior enables you to specify the action to take if an unhandled exception occurs within a workflow service. The Action property specifies one of the WorkflowUnhandledExceptionAction values:

  • Abandon – Aborts the workflow service instance.

  • AbandonAndSuspend – Rolls back to the last persisted state and suspends the workflow service instance. This only occurs if the workflow has already been persisted at least once. If not the workflow instance is aborted.

  • Cancel – Cancels the instance.

  • Terminate – Terminates the instance.

This behavior can be configured in code as shown in the following example.

host.Description.Behaviors.Add(new WorkflowUnhandledExceptionBehavior { Action = WorkflowUnhandledExceptionAction.Abandon });

It can also be configured in a configuration file as shown in the following example.

          <serviceMetadata httpGetEnabled="True"/>
          <serviceDebug includeExceptionDetailInFaults="False" />
          <workflowUnhandledExceptionBehavior action="Abandon" />      

Hosting Non-Service Workflows

WorkflowServiceHost can be used to host non-service workflows, or workflows that either do not begin with a Receive activity or workflows that do not use the messaging activities. Workflow services normally begin with a Receive activity. When the WorkflowServiceHost receives a message for a workflow service, if it is not already running (or persisted) a new workflow service instance is created. If a workflow does not begin with a Receive activity, it cannot be started by sending a message because there is no activity to receive the message. To host a non-service workflow, derive a class from WorkflowHostingEndpoint and override OnGetInstanceId, OnGetCreationContext, and OnResolveBookmark. Override OnGetInstanceId if you want to provide a preferred instance ID. Override OnGetCreationContext to create a custom workflow creation context or populate an instance of the existing WorkflowCreationContext. Override OnResolveBookmark to manually extract the bookmark from the incoming message. If you override this method, you must invoke SendResponse in its body so as to respond to the message sent to the WorkflowHostingEndpoint. If you do not do so, a MaxConcurrentCalls limit may be eventually exceeded. In two-way contracts, you may be able to detect your failure to invoke SendResponse because of the client’s failure to receive a response. In one-way contracts, you may not recognize the mistake of failing to call SendResponse until it’s too late, after the MaxConcurrentCalls throttle limit is exceeded. For more information, please see the Instance creation using WorkflowHostingEndpointTo create a new instance of a non-service workflow, declare a service contract that defines an operation that creates a new instance. The creation operation should take an IDictionary<string, object> to pass any required workflow parameters. This contract is implicitly implemented by the WorkflowHostingEndpoint-derived class. When hosting the workflow, add an instance of the WorkflowHostingEndpoint-derived class to the host by calling AddServiceEndpoint and call Open. To create an instance of the workflow, create a ChannelFactory of your service contract type and call CreateChannel. You can then call the create operation defined in your service contract.

See Also