DispatchRuntime Class

Use the DispatchRuntime class either to modify the default behavior of a service or individual endpoint, or to insert objects that implement custom modifications to one or both of the following service processes:

1. The transformation of incoming messages into objects and releasing those objects as method invocations on a service object.

2. The transformation of objects received from the response to a service operation invocation into outbound messages.

In , the channel and endpoint dispatchers are the service components responsible for accepting new channels, receiving messages, method dispatch and invocation, and response processing. Each endpoint exposed by a ServiceHost object has one endpoint dispatcher and an associated channel dispatcher; in addition, each client that participates in duplex communication also has an endpoint dispatcher and channel dispatcher for each callback endpoint.

The DispatchRuntime enables you to intercept and extend the channel or endpoint dispatcher for all messages across a particular contract, even when a message is not recognized. When a message arrives that does not match any messages declared in the contract it is dispatched to the operation that was returned by the UnhandledDispatchOperation property. To intercept or extend across all messages for a particular operation, see the DispatchOperation class.

There are four main areas of dispatcher extensibility exposed by the DispatchRuntime class:

1. Dispatch components use the properties of the DispatchRuntime and those of the associated channel dispatcher returned by the ChannelDispatcher property to customize how the channel dispatcher accepts and closes channels. This category includes the ChannelInitializers and InputSessionShutdownHandlers properties.

2. Message components are customized for each message processed. This category includes the MessageInspectors, OperationSelector, Operations, and the ErrorHandlers properties.

3. Instance components customize the creation, lifetime, and disposal of instances of the service type. For more information about service object lifetimes, see the InstanceContextMode property. This category includes the InstanceContextInitializers and the InstanceProvider properties.

4. Security-related components can use the following properties:

   • SecurityAuditLogLocation indicates where audit events are written.

   • ImpersonateCallerForAllOperations controls whether the service attempts to impersonate using the credentials provided by the incoming message.

   • MessageAuthenticationAuditLevel controls whether successful message authentication events are written to the event log specified by SecurityAuditLogLocation.

   • PrincipalPermissionMode controls how the CurrentPrincipal property is set.

   • ServiceAuthorizationAuditLevel specifies how the auditing of authorization events is performed.

   • SuppressAuditFailure specifies whether to suppress non-critical exceptions that occur during the logging process.

Typically custom extension objects are assigned to a DispatchRuntime property or inserted into a collection by a service behavior (an object that implements IServiceBehavior), a contract behavior (an object that implements IContractBehavior), or an endpoint behavior (an object that implements IEndpointBehavior). Then the installing behavior object is added to the appropriate collection of behaviors either programmatically or by implementing a custom BehaviorExtensionElement object to enable the behavior to be inserted using an application configuration file.

.NET Framework

.NET Framework Client Profile

Windows 7, Windows Vista SP1 or later, Windows XP SP3, Windows Server 2008 (Server Core not supported), Windows Server 2008 R2 (Server Core supported with SP1 or later), Windows Server 2003 SP2

Reference