Erweitern von VerteilernExtending Dispatchers

Verteiler sind dafür verantwortlich, eingehende Nachrichten aus den zugrunde liegenden Kanälen abzufangen, sie in Methodenaufrufe im Anwendungscode zu übersetzen und die Ergebnisse zurück an den Aufrufer zu senden.Dispatchers are responsible for pulling incoming messages out of the underlying channels, translating them into method invocations in application code, and sending the results back to the caller. Verteilererweiterungen versetzen Sie in die Lage, diese Verarbeitung zu ändern.Dispatcher extensions allow you to modify this processing. Sie können Nachrichten- oder Parameterinspektoren implementieren, die den Inhalt von Nachrichten oder Parametern überprüfen bzw. ändern.You can implement message or parameter inspectors that inspect or modify the contents of messages or parameters. Sie können die Weiterleitung von Nachrichten an Vorgänge ändern oder andere Funktionalität bereitstellen.You can change the way messages are routed to operations or provide some other functionality.

Dieses Thema beschreibt, wie die DispatchRuntime und DispatchOperation Klassen in Windows Communication Foundation (WCF)-dienstanwendung, um das standardausführungsverhalten eines Verteilers zu ändern oder um abfangen oder Ändern von Nachrichten, Parameter oder zurückgeben Werte vor oder nach dem Senden oder sie aus der Kanalschicht abruft.This topic describes how to use the DispatchRuntime and DispatchOperation classes in a Windows Communication Foundation (WCF) service application to modify the default execution behavior of a dispatcher or to intercept or modify messages, parameters, or return values prior to or subsequent to sending or retrieving them from the channel layer. Weitere Informationen über die entsprechenden Client-Runtime-Nachrichtenverarbeitung finden Sie unter Erweitern von Clients.For more information about the equivalent client runtime message processing, see Extending Clients. Um die Rolle zu verstehen, IExtensibleObject<T> Typen finden Sie in den Zugriff auf gemeinsam verwendete Zustände zwischen verschiedenen Laufzeitobjekte Anpassung wiedergeben erweiterbare Objekte.To understand the role that IExtensibleObject<T> types play in accessing shared state between various runtime customization objects, see Extensible Objects.

VerteilerDispatchers

Die Dienstmodellebene führt die Konvertierung zwischen dem Programmiermodell des Entwicklers und dem zugrunde liegenden Nachrichtenaustausch, gewöhnlich als Kanalschicht bezeichnet, durch.The service model layer performs the conversion between the developer’s programming model and the underlying message exchange, commonly called the channel layer. In WCF-Kanal und die Endpunktverteiler (ChannelDispatcher und EndpointDispatcherbzw.) werden die Dienstkomponenten verantwortlich, neue Kanäle, Empfangen von Nachrichten, Vorgänge zu verteilen und Aufruf und Verarbeitung der Antwort zu akzeptieren.In WCF the channel and endpoint dispatchers (ChannelDispatcher and EndpointDispatcher, respectively) are the service components responsible for accepting new channels, receiving messages, operation dispatch and invocation, and response processing. Verteilerobjekte sind empfangende Objekte, aber auch Rückrufvertragsimplementierungen in Duplexdiensten machen ihre Verteilerobjekte für Überprüfung, Änderung oder Erweiterung verfügbar.Dispatcher objects are receiver objects, but callback contract implementations in duplex services also expose their dispatcher objects for inspection, modification, or extension.

Der Kanalverteiler (und der zugehörige IChannelListener) fangen eingehende Nachrichten aus den zugrunde liegenden Kanälen ab und übergeben diese Nachrichten ihren jeweiligen Endpunktverteilern.The channel dispatcher (and companion IChannelListener) pulls messages out of the underling channel and passes the messages to their respective endpoint dispatchers. Jeder Endpunktverteiler hat eine DispatchRuntime, die die Nachrichten an die entsprechende DispatchOperation weiterleitet, die für den Aufruf der Methode verantwortlich ist, die den Vorgang implementiert.Each endpoint dispatcher has a DispatchRuntime that routes messages to the appropriate DispatchOperation, which is responsible for calling the method that implements the operation. Dabei werden verschiedene optionale und notwendige Erweiterungsklassen aufgerufen.Various optional and required extension classes are invoked along the way. In diesem Thema wird erklärt, wie diese Elemente zusammenpassen, und wie Sie deren Eigenschaften ändern und eigenen Code schreiben, um die Basisfunktionalität zu erweitern.This topic explains how these pieces fit together, and how you might modify properties and plug your own code in to extend the base functionality.

Verteilereigenschaften und geänderte Anpassungsobjekte werden mithilfe von Dienst-, Endpunkt-, Vertrags- und Vorgangsverhaltensobjekten eingefügt.Dispatcher properties and modified customization objects are inserted by using service, endpoint, contract, or operation behavior objects. In diesem Thema wird nicht beschrieben, wie Verhaltensobjekte verwendet werden.This topic does not describe how to use behaviors. Weitere Informationen zu den Typen, die zum Einfügen von Änderungen der Verteiler verwendet, finden Sie unter konfigurieren und Erweitern der Laufzeit mit Verhalten.For more information about the types used to insert dispatcher modifications, see Configuring and Extending the Runtime with Behaviors.

Die folgende Grafik bietet einen Überblick über die architektonischen Elemente in einem Dienst.The following graphic provides a high-level view of the architectural items in a service.

Die Architektur der dispatchlaufzeitThe dispatch runtime architecture

KanalverteilerChannel Dispatchers

Ein ChannelDispatcher-Objekt wird erstellt, um einen IChannelListener an einem bestimmten URI (als Abhör-URI bezeichnet) einer Instanz eines Diensts zuzuordnen.A ChannelDispatcher object is created to associate an IChannelListener at a particular URI (called a listen URI) with an instance of a service. Jedes ServiceHost-Objekt kann über viele ChannelDispatcher-Objekte verfügen, die jeweils einem Listener und einem Abhör-URI zugeordnet sind.Each ServiceHost object can have many ChannelDispatcher objects, each associated with only one listener and listen URI. Wenn eine Nachricht eingeht, fragt der ChannelDispatcher jedes der zugeordneten EndpointDispatcher-Objekte ab, ob der Endpunkt die Nachricht akzeptieren kann, und leitet die Nachricht an den Endpunkt weiter, der dies kann.When a message arrives, the ChannelDispatcher queries each of the associated EndpointDispatcher objects whether the endpoint can accept the message, and passes the message to the one that can.

Alle Eigenschaften, die die Lebensdauer und das Verhalten einer Kanalsitzung steuern, sind zur Überprüfung oder Änderung im ChannelDispatcher-Objekt verfügbar.All properties that control the lifetime and behavior of a channel session are available for inspection or modification on the ChannelDispatcher object. Dies schließt benutzerdefinierte Kanalinitialisierer, den Kanallistener, den Host, den zugeordneten InstanceContext usw. ein.These include custom channel initializers, the channel listener, the host, the associated InstanceContext, and so on.

EndpunktverteilerEndpoint Dispatchers

Das EndpointDispatcher-Objekt ist verantwortlich für das Verarbeiten von Nachrichten von einem ChannelDispatcher, wenn die Zieladresse einer Nachricht mit der AddressFilter-Eigenschaft übereinstimmt und die Nachrichtenaktion mit der ContractFilter-Eigenschaft übereinstimmt.The EndpointDispatcher object is responsible for processing messages from a ChannelDispatcher when the destination address of a message matches the AddressFilter and the message action matches the ContractFilter property. Wenn zwei EndpointDispatcher-Objekte eine Nachricht akzeptieren können, bestimmt der Wert der FilterPriority-Eigenschaft den Endpunkt mit höherer Priorität.If two EndpointDispatcher objects can accept a message, the FilterPriority property value determines the higher priority endpoint.

Verwenden Sie das EndpointDispatcher-Objekt, um die beiden Haupterweiterungspunkte des Dienstmodells – die DispatchRuntime-Klasse und die DispatchOperation-Klasse – abzurufen, die Sie verwenden können, um die Verarbeitung durch den Verteiler anzupassen.Use the EndpointDispatcher to acquire the two main service model extension points – the DispatchRuntime and DispatchOperation classes – that you can use to customize the processing of the dispatcher. Die DispatchRuntime-Klasse ermöglicht Benutzern, den Verteiler im Vertragsbereich (also für alle Nachrichten in einem Vertrag) abzufangen und zu erweitern.The DispatchRuntime class allows users to intercept and extend the dispatcher at the contract scope (that is, for all messages in a contract). Die DispatchOperation-Klasse ermöglicht Benutzern, den Verteiler im Vorgangsbereich (also für alle Nachrichten in einem Vorgang) abzufangen und zu erweitern.The DispatchOperation class allows users to intercept and extend the dispatcher at an operation scope (that is, for all messages in an operation).

SzenarienScenarios

Es gibt eine Reihe von Gründen, den Verteiler zu erweitern:There a number of reasons to extend the dispatcher:

  • Benutzerdefinierte Nachrichtenvalidierung.Custom Message Validation. Benutzer können durchsetzen, dass eine Nachricht für ein bestimmtes Schema gültig ist.Users can enforce that a message is valid for a certain schema. Dies kann über die Implementierung der Nachrichteninterceptorschnittstellen erreicht werden.This can be done by implementing the message interceptor interfaces. Ein Beispiel finden Sie unter Nachrichteninspektoren.For an example, see Message Inspectors.

  • Benutzerdefinierte Nachrichtenprotokollierung.Custom Message Logging. Benutzer können einige Anwendungsnachrichten prüfen und protokollieren, die durch einen Endpunkt fließen.Users can inspect and log some set of application messages that flow through an endpoint. Dies kann ebenfalls mit den Nachrichteninterceptorschnittstellen erreicht werden.This can also be accomplished with the message interceptor interfaces.

  • Benutzerdefinierte Nachrichtentransformationen.Custom Message Transformations. Benutzer können bestimmte Transformationen (beispielsweise die Versionsverwaltung) auf die Nachricht in der Laufzeit anwenden.Users can apply certain transformations to the message in the runtime (for example, for versioning). Auch dies kann mit den Nachrichteninterceptorschnittstellen erreicht werden.This can be accomplished, again, with the message interceptor interfaces.

  • Benutzerdefiniertes Datenmodell.Custom Data Model. Benutzer können ein Datenmodell für die Serialisierung nicht unterstützt, die standardmäßig in WCF verfügen (d. h., System.Runtime.Serialization.DataContractSerializer, System.Xml.Serialization.XmlSerializer, und unformatierte Nachrichten).Users can have a data serialization model other than those supported by default in WCF (namely, System.Runtime.Serialization.DataContractSerializer, System.Xml.Serialization.XmlSerializer, and raw messages). Dies kann über die Implementierung der Nachrichtenformatierungsschnittstellen erreicht werden.This can be done by implement the message formatter interfaces. Ein Beispiel finden Sie unter Vorgangsformatierer und Vorgangsauswahl.For an example, see Operation Formatter and Operation Selector.

  • Benutzerdefinierte Parametervalidierung.Custom Parameter Validation. Benutzer können durchsetzen, dass typisierte Parameter gültig sind (im Gegensatz zu XML).Users can enforce that typed parameters are valid (as opposed to XML). Dies kann mit den Parameterinspektorschnittstellen erreicht werden.This can be done using the parameter inspector interfaces.

  • Benutzerdefinierte Vorgangsverteilung.Custom Operation Dispatching. Benutzer können die Verteilung an etwas anderes als an eine Aktion implementieren – beispielsweise an das Textelement oder an eine benutzerdefinierte Nachrichteneigenschaft.Users can implement dispatching on something other than action – for example, on the body element, or on a custom message property. Dies kann über die Verwendung der IDispatchOperationSelector-Schnittstelle erreicht werden.This can be done using the IDispatchOperationSelector interface. Ein Beispiel finden Sie unter Vorgangsformatierer und Vorgangsauswahl.For an example, see Operation Formatter and Operation Selector.

  • Objektpooling.Object Pooling. Benutzer können Instanzen zusammenlegen, statt für jeden Aufruf eine neue Instanz zuzuordnen.Users can pool instances rather than allocating a new one for every call. Dies kann über die Implementierung der Instanzanbieterschnittstellen erreicht werden.This can be implemented using the instance provider interfaces. Ein Beispiel finden Sie unter Pooling.For an example, see Pooling.

  • Instanzleasing.Instance Leasing. Benutzer können ein Leasingmuster ähnlich dem von .NET Framework Remoting für die Lebensdauer der Instanz implementieren.Users can implement a leasing pattern for instance lifetime, similar to that of .NET Framework Remoting. Dies kann mit den Instanzkontextlebensdauer-Schnittstellen erreicht werden.This can be done using the instance context lifetime interfaces.

  • Benutzerdefinierte Fehlerbehandlung.Custom Error Handling. Benutzer können steuern, wie lokale Fehler verarbeitet werden und wie Clients über Fehler unterrichtet werden.Users can control how both local errors are processed and how faults are communicated back to clients. Dies kann mithilfe der IErrorHandler-Schnittstellen implementiert werden.This can be implemented using the IErrorHandler interfaces.

  • Benutzerdefiniertes AutorisierungsverhaltenCustom Authorization Behaviors. Benutzer können eine benutzerdefinierte Zugriffssteuerung implementieren, indem sie die Vertrags- und Vorgangslaufzeitelemente erweitern und auf in der Nachricht enthaltenen Tokens basierende Sicherheitsüberprüfungen hinzufügen.Users can implement custom access control by extending the Contract or Operation run-time pieces and adding security checks based upon the tokens present in the message. Dies kann entweder mit den Nachrichteninterceptor- oder den Parameterinterceptorschnittstellen erreicht werden.This can be accomplished using either the message interceptor or parameter interceptor interfaces. Beispiele finden Sie unter Sicherheitserweiterbarkeit.For examples, see Security Extensibility.

    Achtung

    Da Ändern der Sicherheitseigenschaften potenziell gefährdet die Sicherheit des WCF-Anwendungen hat, wird empfohlen, dass Sie sicherheitsbezogene Änderungen mit Sorgfalt verpflichten und vor der Bereitstellung gründlich testen.Because altering security properties has the potential to compromise the security of WCF applications, it is strongly recommended that you undertake security-related modifications with care and test thoroughly prior to deployment.

  • Benutzerdefinierte WCF-Laufzeitvalidierungs-Steuerelemente.Custom WCF Runtime Validators. Sie können benutzerdefinierte laufzeitvalidierungs-Steuerelemente installieren, die überprüfen, Dienste, Verträge und Bindungen, um Sicherheitsrichtlinien auf Unternehmensebene in Bezug auf die WCF-Anwendungen zu erzwingen.You can install custom validators that examine services, contracts, and bindings to enforce enterprise-level policies with respect to WCF applications. (Z. B. finden Sie unter Vorgehensweise: Sperren Sie die Endpunkte im Unternehmen.)(For example, see How to: Lock Down Endpoints in the Enterprise.)

Verwenden der DispatchRuntime-KlasseUsing the DispatchRuntime Class

Verwenden Sie die DispatchRuntime-Klasse, um entweder das Standardverhalten eines Diensts oder eines einzelnen Endpunkts zu ändern, oder um Objekte einzufügen, die benutzerdefinierte Änderungen für einen oder für beide der folgenden Dienstprozesse implementieren (oder für Clientprozesse im Fall eines Duplexclients):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 (or client processes in the case of a duplex client):

  • Die Transformation eingehender Nachrichten in Objekte und die Freigabe dieser Objekte als Methodenaufrufe in einem Dienstobjekt.The transformation of incoming messages into objects and releasing those objects as method invocations on a service object.

  • Die Transformation von Objekten, die von der Antwort auf einen Dienstvorgangsaufruf empfangen wurden, in ausgehende Nachrichten.The transformation of objects received from the response to a service operation invocation into outbound messages.

Die DispatchRuntime-Klasse ermöglicht Ihnen, den Kanal- oder Endpunktverteiler für alle Nachrichten in einem bestimmten Vertrag auch dann abzufangen und zu erweitern, wenn eine Nachricht nicht erkannt wurde.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. Wenn eine Nachricht eintrifft, die mit keinem im Vertrag deklarierten Vorgang übereinstimmt, wird sie an den Vorgang geleitet, der von der UnhandledDispatchOperation-Eigenschaft zurückgegeben wird.When a message arrives that does not match any declared in the contract it is dispatched to the operation returned by the UnhandledDispatchOperation property. Informationen dazu, wie ein Verteiler erweitert wird, der alle Nachrichten für einen bestimmten Vorgang abfängt, finden Sie unter der DispatchOperation-Klasse.To intercept or extend across all messages for a particular operation, see the DispatchOperation class.

Es gibt vier Hauptbereiche der Verteilererweiterbarkeit, die von der DispatchRuntime-Klasse verfügbar gemacht werden:There are four main areas of dispatcher extensibility exposed by the DispatchRuntime class:

  1. Kanalkomponenten verwenden Eigenschaften der DispatchRuntime-Klasse sowie jene des zugeordneten Kanalverteilers, der von der ChannelDispatcher-Eigenschaft zurückgegeben wird, um festzulegen, wie der Kanalverteiler Kanäle akzeptiert und schließt.Channel 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. Dazu gehören die Eigenschaften ChannelInitializers und InputSessionShutdownHandlers.This category includes the ChannelInitializers and InputSessionShutdownHandlers properties.

  2. Nachrichtenkomponenten werden für jede verarbeitete Nachricht angepasst.Message components are customized for each message processed. Dazu gehören die Eigenschaften MessageInspectors, OperationSelector, Operations und ErrorHandlers.This category includes the MessageInspectors, OperationSelector, Operations, and the ErrorHandlers properties.

  3. Instanzkomponenten passen die Erstellung, Lebensdauer und Freigabe von Instanzen des Diensttyps an.Instance components customize the creation, lifetime, and disposal of instances of the service type. Weitere Informationen zur Lebensdauer von Dienstobjekten finden Sie in den Ausführungen zur InstanceContextMode-Eigenschaft.For more information about service object lifetimes, see the InstanceContextMode property. Dazu gehören die Eigenschaften InstanceContextInitializers und InstanceProvider.This category includes the InstanceContextInitializers and the InstanceProvider properties.

  4. Sicherheitsrelevante Komponenten können die folgenden Eigenschaften verwenden:Security-related components can use the following properties:

In der Regel werden benutzerdefinierte Erweiterungsobjekte einer DispatchRuntime-Eigenschaft zugewiesen oder durch ein Dienstverhalten (ein Objekt, das IServiceBehavior implementiert), durch ein Vertragsverhalten (ein Objekt, das IContractBehavior implementiert) oder durch ein Endpunktverhalten (ein Objekt, das IEndpointBehavior implementiert) in eine Auflistung eingefügt.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). Das installierende Verhaltensobjekt wird dann der entsprechenden Verhaltensauflistung entweder programmgesteuert oder durch Implementierung eines benutzerdefinierten BehaviorExtensionElement-Objekts hinzugefügt, um das Verhalten, das eingefügt werden soll, mithilfe einer Anwendungskonfigurationsdatei zu aktivieren.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.

Duplexclients (Clients, die den durch einen Duplexdienst angegebenen Rückrufvertrag implementieren) verfügen auch über ein DispatchRuntime-Objekt, auf das mithilfe der CallbackDispatchRuntime-Eigenschaft zugegriffen werden kann.Duplex clients (clients that implement a callback contract specified by a duplex service) also have a DispatchRuntime object that can be accessed using the CallbackDispatchRuntime property.

Verwenden der DispatchOperation-KlasseUsing the DispatchOperation Class

Die DispatchOperation-Klasse ist der Speicherort für Laufzeitänderungen und die Einfügemarke für benutzerdefinierte Erweiterungen, die nur auf einen Dienstvorgang abzielen.The DispatchOperation class is the location for run-time modifications and the insertion point for custom extensions that are scoped to only one service operation. (Um das Dienstlaufzeit-Verhalten für alle Nachrichten in einem Vertrag zu ändern, verwenden Sie die DispatchRuntime-Klasse.)(To modify service run-time behavior for all messages in a contract, use the DispatchRuntime class.)

Installieren Sie DispatchOperation-Änderungen mithilfe eines benutzerdefinierten Dienstverhaltensobjekts.Install DispatchOperation modifications using a custom service behavior object.

Verwenden Sie die Operations-Eigenschaft, um das DispatchOperation-Objekt zu suchen, das einen bestimmten Dienstvorgang darstellt.Use the Operations property to locate the DispatchOperation object that represents a particular service operation.

Die folgenden Eigenschaften kontrollieren die Laufzeitausführung auf Vorgangsebene:The following properties control runtime execution at the operation level:

Siehe auchSee Also

DispatchRuntime
DispatchOperation
Vorgehensweise: Überprüfen und Ändern von Nachrichten für den DienstHow to: Inspect and Modify Messages on the Service
Vorgehensweise: Überprüfen oder Ändern von ParameternHow to: Inspect or Modify Parameters
Vorgehensweise: Sperren von Endpunkten im UnternehmenHow to: Lock Down Endpoints in the Enterprise