Erweitern von ClientsExtending Clients

Die Dienstmodellebene ist dafür verantwortlich, Methodenaufrufe per Anwendungscode in ausgehende Nachrichten zu übersetzen, sie in den zugrunde liegenden Kanälen abzulegen, die Ergebnisse zurück in Rückgabewerte und out-Parameter in Anwendungscode zu übersetzen sowie die Ergebnisse an den Aufrufer zurückzugeben.In a calling application, the service model layer is responsible for translating method invocations in application code into outbound messages, pushing them to the underlying channels, translating results back into return values and out parameters in application code, and returning the results back to the caller. Dienstmodellerweiterungen ändern bzw. implementieren Ausführungs- oder Kommunikationsverhalten und Funktionen wie Verteileroptionen, benutzerdefiniertes Verhalten, Nachrichten- oder Parameterinterceptoren und andere Erweiterbarkeitsfunktionen.Service model extensions modify or implement execution or communication behavior and features involving client or dispatcher functionality, custom behaviors, message and parameter interception, and other extensibility functionality.

Dieses Thema beschreibt, wie die ClientRuntime und ClientOperation Klassen in einer Clientanwendung Windows Communication Foundation (WCF) ändern das Standardverhalten für die Ausführung eines WCF-Clients zum Abfangen oder Ändern von Nachrichten, Parameter oder Rückgabewerte vor oder nach dem Senden oder sie aus der Kanalschicht abruft.This topic describes how to use the ClientRuntime and ClientOperation classes in a Windows Communication Foundation (WCF) client application to modify the default execution behavior of a WCF client 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 zum Erweitern der Service Runtime finden Sie unter Erweitern von Verteilern.For more information about extending the service runtime, see Extending Dispatchers. Weitere Informationen zu den Verhaltensweisen, die ändern und Anpassung von Objekten in die Clientlaufzeit einfügen, finden Sie unter konfigurieren und Erweitern der Laufzeit mit Verhalten.For more information about the behaviors that modify and insert customization objects into the client runtime, see Configuring and Extending the Runtime with Behaviors.

ClientsClients

Auf einem Client konvertiert ein WCF-Client-Objekt oder -Clientkanal Methodenaufrufe in ausgehende Nachrichten und eingehende Nachrichten in Vorgangsergebnisse, die an die aufrufende Anwendung zurückgegeben werden.On a client, a WCF client object or client channel converts method invocations into outgoing messages and incoming messages to operation results that are returned to the calling application. (Weitere Informationen zu Clienttypen finden Sie unter WCF-Clientarchitektur.)(For more information about client types, see WCF Client Architecture.)

WCF-Clienttypen weisen Laufzeittypen auf, die diese Funktionalität Endpunkt und Vorgangsebene verarbeiten.WCF client types have runtime types that handle this endpoint- and operation-level functionality. Wenn ein Vorgang von einer Anwendung aufgerufen wird, übersetzt ClientOperation die ausgehenden Objekte in eine Nachricht, verarbeitet Interceptoren, bestätigt, dass der ausgehende Aufruf dem Zielvertrag entspricht, und übergibt die ausgehende Nachricht an ClientRuntime, die für das Erstellen und Verwalten von ausgehenden Kanälen (und eingehenden Kanälen im Falle von Duplexdiensten), das Verarbeiten von zusätzlichen ausgehenden Nachrichten (wie Headeränderungen), die Verarbeitung von Nachrichteninterceptoren in beide Richtungen sowie das Leiten von eingehenden Duplexaufrufen an das entsprechende clientseitige DispatchRuntime-Objekt verantwortlich ist.When an application calls an operation, the ClientOperation translates the outbound objects into a message, processes interceptors, confirms that the outbound call conforms to the target contract, and hands the outbound message to the ClientRuntime, which is responsible for creating and managing outbound channels (and inbound channels in the case of duplex services), handling extra outbound message processing (such as header modification), processing message interceptors in both directions, and routing inbound duplex calls to the appropriate client-side DispatchRuntime object. Sowohl ClientOperation als auch ClientRuntime stellen ähnliche Dienste bereit, wenn dem Client Nachrichten (einschließlich Fehler) zurückgegeben werden.Both the ClientOperation and ClientRuntime provide similar services when messages (including faults) are returned to the client.

Diese beiden Laufzeitklassen stellen die haupterweiterung dar, die Verarbeitung von WCF-Clientobjekten und Kanäle anpassen.These two runtime classes are the main extension to customize the processing of WCF client objects and channels. Die ClientRuntime-Klasse ermöglicht Benutzern, die Clientausführung über alle Nachrichten im Vertrag hinweg abzufangen und zu erweitern.The ClientRuntime class allows users to intercept and extend client execution across all messages in the contract. Die ClientOperation-Klasse ermöglicht Benutzern, die Clientausführung für alle Nachrichten eines bestimmten Vorgangs abzufangen und zu erweitern.The ClientOperation class allows users to intercept and extend client execution for all messages in a given operation.

Das Ändern der Eigenschaften oder Einfügen von Anpassungen wird auf der Grundlage von Vertrags-, Endpunkt- und Vorgangsverhalten durchgeführt.Modifying the properties or inserting customizations are done by using contract, endpoint, and operation behaviors. Weitere Informationen zur Verwendung dieser Typen von Verhaltensweisen zum Ausführen von Client-Runtime-Anpassungen finden Sie unter konfigurieren und Erweitern der Laufzeit mit Verhalten.For more information about how to use these types of behaviors to perform client runtime customizations, see Configuring and Extending the Runtime with Behaviors.

SzenarienScenarios

Es gibt viele Gründe, das Clientsystem zu erweitern:There a number of reasons to extend the client system, including:

Verwenden der ClientRuntime-KlasseUsing the ClientRuntime Class

Die ClientRuntime-Klasse ist ein Erweiterungspunkt, an den Sie Erweiterungsobjekte anhängen können, die Nachrichten abfangen und das Clientverhalten ausdehnen.The ClientRuntime class is an extensibility point to which you can add extension objects that intercept messages and extend client behavior. Abfangobjekte können alle Nachrichten in einem bestimmten Vertrag verarbeiten, nur Nachrichten für bestimmte Vorgänge verarbeiten, eine benutzerdefinierte Kanalinitialisierung durchführen und sonstiges benutzerdefiniertes Verhalten von Clientanwendungen implementieren.Interception objects can process all messages in a particular contract, process only messages for particular operations, perform custom channel initialization, and implement other custom client application behavior.

  • Die CallbackDispatchRuntime-Eigenschaft gibt das DispatchRuntime-Objekt für durch Dienste initiierte Rückrufvorgangsclients zurück.The CallbackDispatchRuntime property returns the dispatch run-time object for service-initiated callback clients.

  • Die OperationSelector-Eigenschaft akzeptiert ein benutzerdefiniertes Vorgangsauswahlobjekt.The OperationSelector property accepts a custom operation selector object.

  • Die ChannelInitializers-Eigenschaft ermöglicht das Hinzufügen eines Kanalinitialisierers, der den Clientkanal prüfen oder abändern kann.The ChannelInitializers property enables the addition of a channel initializer that can inspect or modify the client channel.

  • Die Operations-Eigenschaft ruft eine Auflistung von ClientOperation-Objekten ab, denen Sie benutzerdefinierte Nachrichteninterceptoren hinzufügen können, die spezielle Funktionen für die Nachrichten dieses Vorgangs bereitstellen.The Operations property gets a collection of ClientOperation objects to which you can add custom message interceptors that provide functionality specific to the messages of that operation.

  • Die ManualAddressing-Eigenschaft ermöglicht einer Anwendung, bestimmte automatische Adressierungsheader zu deaktivieren, um die Adressierung direkt zu steuern.The ManualAddressing property enables an application to turn off some automatic addressing headers to directly control addressing.

  • Die Via-Eigenschaft legt den Wert des Ziels der Nachricht auf der Transportebene fest, um Vermittler und andere Szenarien zu unterstützen.The Via property sets the value of the destination of the message at the transport level to support intermediaries and other scenarios.

  • Die MessageInspectors Eigenschaft ruft eine Auflistung von IClientMessageInspector Objekte, denen Sie benutzerdefinierte nachrichteninterceptoren für alle Nachrichten über einen WCF-Client hinzufügen können.The MessageInspectors property gets a collection of IClientMessageInspector objects to which you can add custom message interceptors for all messages traveling through a WCF client.

Außerdem gibt es eine Reihe weiterer Eigenschaften, die die Clientvertragsinformationen abrufen:In addition, there are a number of other properties that retrieve the contract information:

Wenn der WCF-Client einen WCF-duplexclient handelt, abgerufen werden die folgenden Eigenschaften auch den Rückruf WCF-Client-Informationen:If the WCF client is a duplex WCF client, the following properties also retrieve the callback WCF client information:

Um die Ausführung der WCF-Client über eine gesamte WCF-Client zu erweitern, überprüfen Sie die Eigenschaften, die über die ClientRuntime Klasse, um festzustellen, ob das Ändern einer Eigenschaft oder das Implementieren einer Schnittstelle und Hinzufügen einer Eigenschaft die Funktionalität ausdehnen möchten.To extend WCF client execution across an entire WCF client, review the properties available on the ClientRuntime class to see whether modifying a property or implementing an interface and adding it to a property creates the functionality you are seeking. Sobald Sie eine bestimmte Erweiterung ausgewählt haben, müssen Sie Ihre Erweiterung in die geeignete ClientRuntime-Eigenschaft einfügen, indem Sie ein Clientverhalten implementieren, das Zugriff auf die ClientRuntime-Klasse bietet, sobald diese aufgerufen wird.Once you have chosen a particular extension to build, insert your extension into the appropriate ClientRuntime property by implementing a client behavior that provides access to the ClientRuntime class when invoked.

Sie können benutzerdefinierte Erweiterungsobjekte in eine Auflistung einfügen. Verwenden Sie dazu ein Vorgangsverhalten (ein Objekt, das IOperationBehavior implementiert), ein Vertragsverhalten (ein Objekt, das IContractBehavior implementiert) oder ein Endpunktverhalten (ein Objekt, das IEndpointBehavior implementiert).You can insert custom extension objects into a collection using an operation behavior (an object that implements IOperationBehavior), a contract behavior (an object that implements IContractBehavior), or an endpoint behavior (an object that implements IEndpointBehavior). Das installierende Verhaltensobjekt wird der entsprechenden Auflistung der Verhalten entweder programmatisch, deklarativ (durch Implementierung eines benutzerdefinierten Attributs) oder durch Implementierung eines benutzerdefinierten BehaviorExtensionElement-Objekts hinzugefügt, um das Verhalten, das eingefügt werden soll, anhand einer Anwendungskonfigurationsdatei zu aktivieren.The installing behavior object is added to the appropriate collection of behaviors either programmatically, declaratively (by implementing a custom attribute), or by implementing a custom BehaviorExtensionElement object to enable the behavior to be inserted using an application configuration file. Weitere Informationen finden Sie unter konfigurieren und Erweitern der Laufzeit mit Verhalten.For details, see Configuring and Extending the Runtime with Behaviors.

Beispiele für die Abfangfunktion über einen WCF-Client finden Sie unter Vorgehensweise: Überprüfen oder Ändern von Nachrichten auf dem Client.For examples that demonstrate interception across a WCF client, see How to: Inspect or Modify Messages on the Client.

Verwenden der ClientOperation-KlasseUsing the ClientOperation Class

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

Verwenden Sie die Operations-Eigenschaft, um das ClientOperation-Objekt zu suchen, das einen bestimmten Dienstvorgang darstellt.Use the Operations property to locate the ClientOperation object that represents a particular service operation. Die folgenden Eigenschaften ermöglichen es Ihnen, benutzerdefinierte Objekte in der WCF-Clientsystem einzufügen:The following properties enable you to insert custom objects into the WCF client system:

Mit den folgenden Eigenschaften können Sie das System in Interaktion mit dem Formatierungsprogramm und benutzerdefinierten Parameterinspektoren ändern:The following properties enable you to modify the system in interaction with the formatter and custom parameter inspectors:

  • Verwenden Sie die SerializeRequest-Eigenschaft, um die Serialisierung einer ausgehenden Nachricht zu steuern.Use the SerializeRequest property to control the serialization of an outbound message.

  • Verwenden Sie die DeserializeReply-Eigenschaft, um die Deserialisierung einer eingehenden Nachricht zu steuern.Use the DeserializeReply property to control the deserialization of an inbound message.

  • Verwenden Sie die Action-Eigenschaft, um die WS-Adressierungsaktion der Anforderungsnachricht zu steuern.Use the Action property to control the WS-Addressing action of the request message.

  • Verwenden der BeginMethod und EndMethod angeben, welche WCF-Clientmethoden einem asynchronen Vorgang zugeordnet sind.Use the BeginMethod and EndMethod to specify which WCF client methods are associated with an asynchronous operation.

  • Verwenden Sie die FaultContractInfos-Eigenschaft, um eine Auflistung der angegebenen Typen abzurufen, die als Detailtyp in SOAP-Fehlern erscheinen können.Use the FaultContractInfos property to get a collection that contains the types that can appear in SOAP faults as the detail type.

  • Verwenden Sie die IsInitiating-Eigenschaft und die IsTerminating-Eigenschaft, um zu steuern, ob eine Sitzung initiiert bzw. abgebrochen wird, wenn der Vorgang aufgerufen wird.Use the IsInitiating and IsTerminating properties to control whether a session is initiated or is torn down, respectively, when the operation is called.

  • Verwenden Sie die IsOneWay-Eigenschaft, um zu steuern, ob es sich bei dem Vorgang um einen unidirektionalen Vorgang handelt.Use the IsOneWay property to control whether the operation is a one-way operation.

  • Verwenden Sie die Parent-Eigenschaft, um das darin enthaltene ClientRuntime-Objekt zu ermitteln.Use the Parent property to obtain the containing ClientRuntime object.

  • Verwenden Sie die Name-Eigenschaft, um den Namen des Vorgangs abzurufen.Use the Name property to get the name of the operation.

  • Verwenden Sie die SyncMethod-Eigenschaft, um zu steuern, welche Methode dem Vorgang zugeordnet wird.Use the SyncMethod property to control which method is mapped to the operation.

Um WCF-clientausführung über nur einen Dienstvorgang zu erweitern, überprüfen Sie die Eigenschaften, die verfügbar sind, auf die ClientOperation Klasse, um festzustellen, ob das Ändern einer Eigenschaft oder das Implementieren einer Schnittstelle und Hinzufügen einer Eigenschaft die Funktionalität ausdehnen möchten.To extend WCF client execution across only one service operation, review the properties available on the ClientOperation class to see whether modifying a property or implementing an interface and adding it to a property creates the functionality you are seeking. Sobald Sie eine bestimmte Erweiterung ausgewählt haben, müssen Sie Ihre Erweiterung in die geeignete ClientOperation-Eigenschaft einfügen, indem Sie ein Clientverhalten implementieren, das Zugriff auf die ClientOperation-Klasse bietet, sobald diese aufgerufen wird.Once you have chosen a particular extension to build, insert your extension into the appropriate ClientOperation property by implementing a client behavior that provides access to the ClientOperation class when invoked. In diesem Verhalten können Sie dann die ClientRuntime-Eigenschaft ändern, um sie Ihren Anforderungen anzupassen.Inside that behavior you can then modify the ClientRuntime property to fit your requirements.

In der Regel reicht die Implementierung eines Vorgangsverhaltens (ein Objekt, das die IOperationBehavior-Schnittstelle implementiert) aus, Sie können jedoch auch Endpunktverhalten und Vertragsverhalten verwenden, um dasselbe zu erreichen, indem Sie OperationDescription für einen bestimmten Vorgang suchen und dort das Verhalten anfügen.Typically, implementing an operation behavior (an object that implements the IOperationBehavior interface) suffices, but you can also use endpoint behaviors and contract behaviors to accomplish the same thing by locating the OperationDescription for a particular operation and attaching the behavior there. Weitere Informationen finden Sie unter konfigurieren und Erweitern der Laufzeit mit Verhalten.For details, see Configuring and Extending the Runtime with Behaviors.

Um das benutzerdefinierte Verhalten der Konfiguration zu verwenden, installieren Sie das Verhalten mit einem benutzerdefinierten Verhaltenskonfigurationsabschnitts-Handler.To use your custom behavior from configuration, install your behavior using a custom behavior configuration section handler. Sie können auch das Verhalten installieren, indem Sie ein benutzerdefiniertes Attribut erstellen.You can also install your behavior by creating a custom attribute.

Beispiele für die Abfangfunktion über einen WCF-Client finden Sie unter Vorgehensweise: Überprüfen oder ändern Parameter.For examples that demonstrate interception across a WCF client, see How to: Inspect or Modify Parameters.

Siehe auchSee Also

ClientRuntime
ClientOperation
Vorgehensweise: Überprüfen oder Ändern von Nachrichten auf dem ClientHow to: Inspect or Modify Messages on the Client
Vorgehensweise: Überprüfen oder Ändern von ParameternHow to: Inspect or Modify Parameters