Erweitern von 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. Dienstmodellerweiterungen ändern bzw. implementieren Ausführungs- oder Kommunikationsverhalten und Funktionen wie Verteileroptionen, benutzerdefiniertes Verhalten, Nachrichten- oder Parameterinterceptoren und andere Erweiterbarkeitsfunktionen.
In diesem Thema wird beschrieben, wie Klassen ClientRuntime und ClientOperation in einer WCF-Clientanwendung (Windows Communication Foundation) verwendet werden, um das Standardausführungsverhalten eines WCF-Clients zu ändern, oder um Nachrichten, Parameter oder Rückgabewerte abzufangen oder zu ändern, bevor oder nachdem sie aus der Kanalschicht gesendet oder abgerufen werden. Weitere Informationen zur Ausdehnung der Dienstlaufzeit finden Sie unter Erweitern von Verteilern. Weitere Informationen über das Verhalten, bei dem Anpassungsobjekte in die Clientlaufzeit eingefügt oder geändert werden, finden Sie unter Konfigurieren und Erweitern der Laufzeit mit Verhalten.
Clients
Auf einem Client konvertiert ein WCF-Clientobjekt oder -Clientkanal Methodenaufrufe in ausgehende Nachrichten und eingehende Nachrichten in Vorgangsergebnisse, die an die aufrufende Anwendung zurückgegeben werden. (Weitere Informationen zu Clienttypen finden Sie unter WCF-Clientarchitektur.)
WCF-Clienttypen weisen Laufzeittypen auf, die diese Funktionen auf Endpunkt- und Vorgangsebene verarbeiten. 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. Sowohl ClientOperation als auch ClientRuntime stellen ähnliche Dienste bereit, wenn dem Client Nachrichten (einschließlich Fehler) zurückgegeben werden.
Diese beiden Laufzeitklassen stellen die Haupterweiterung dar, um die Verarbeitung von WCF-Clientobjekten und -Clientkanälen anzupassen. Die ClientRuntime-Klasse ermöglicht Benutzern, die Clientausführung über alle Nachrichten im Vertrag hinweg abzufangen und zu erweitern. Die ClientOperation-Klasse ermöglicht Benutzern, die Clientausführung für alle Nachrichten eines bestimmten Vorgangs abzufangen und zu erweitern.
Das Ändern der Eigenschaften oder Einfügen von Anpassungen wird auf der Grundlage von Vertrags-, Endpunkt- und Vorgangsverhalten durchgeführt. Weitere Informationen über die Anwendung dieser Verhaltenstypen zum Durchführen von Clientlaufzeitanpassungen finden Sie unter Konfigurieren und Erweitern der Laufzeit mit Verhalten.
Szenarien
Es gibt viele Gründe, das Clientsystem zu erweitern:
Benutzerdefinierte Nachrichtenvalidierung. Ein Benutzer möchte durchsetzen, dass eine Nachricht für ein bestimmtes Schema gültig ist. Dies kann durch Implementieren der IClientMessageInspector-Schnittstelle und Zuweisen der Implementierung an die MessageInspectors-Eigenschaft erfolgen. Beispiele finden Sie unter Vorgehensweise: Überprüfen oder Ändern von Nachrichten auf dem Client und Vorgehensweise: Überprüfen oder Ändern von Nachrichten auf dem Client.
Benutzerdefinierte Nachrichtenprotokollierung. Ein Benutzer möchte eventuell einige Anwendungsnachrichten prüfen und protokollieren, die durch einen Endpunkt fließen. Dies kann ebenfalls mit den Nachrichteninterceptorschnittstellen erreicht werden.
Benutzerdefinierte Nachrichtentransformationen. Anstatt den Anwendungscode zu ändern, möchte der Benutzer vielleicht bestimmte Transformationen (wie Versionsverwaltung) auf die Nachricht in der Laufzeit anwenden. Auch dies kann mit den Nachrichteninterceptorschnittstellen erreicht werden.
Benutzerdefiniertes Datenmodell. Ein Benutzer möchte eventuell über ein anderes Daten- oder Serialisierungsmodell verfügen als die standardmäßig in WCF unterstützten (nämlich System.Runtime.Serialization.DataContractSerializer-, System.Xml.Serialization.XmlSerializer- und System.ServiceModel.Channels.Message-Objekte). Dies kann über die Implementierung der Nachrichtenformatierungsschnittstellen erreicht werden. Weitere Informationen finden Sie in der System.ServiceModel.Dispatcher.IClientMessageFormatter-Eigenschaft und in der ClientOperation.Formatter-Eigenschaft.
Benutzerdefinierte Parametervalidierung. Ein Benutzer möchte durchsetzen, dass typisierte Parameter gültig sind (im Gegensatz zu XML). Dies kann mit den Parameterinspektorschnittstellen erreicht werden. Ein Beispiel finden Sie unter Vorgehensweise: Überprüfen oder Ändern von Parametern oder Clientvalidierung.
Verwenden der ClientRuntime-Klasse
Die ClientRuntime-Klasse ist ein Erweiterungspunkt, an den Sie Erweiterungsobjekte anhängen können, die Nachrichten abfangen und das Clientverhalten ausdehnen. 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.
Die CallbackDispatchRuntime-Eigenschaft gibt das DispatchRuntime-Objekt für durch Dienste initiierte Rückrufvorgangsclients zurück.
Die OperationSelector-Eigenschaft akzeptiert ein benutzerdefiniertes Vorgangsauswahlobjekt.
Die ChannelInitializers-Eigenschaft ermöglicht das Hinzufügen eines Kanalinitialisierers, der den Clientkanal prüfen oder abändern kann.
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.
Die ManualAddressing-Eigenschaft ermöglicht einer Anwendung, bestimmte automatische Adressierungsheader zu deaktivieren, um die Adressierung direkt zu steuern.
Die Via-Eigenschaft legt den Wert des Ziels der Nachricht auf der Transportebene fest, um Vermittler und andere Szenarien zu unterstützen.
Die MessageInspectors-Eigenschaft ruft eine Auflistung von IClientMessageInspector-Objekten ab, denen Sie benutzerdefinierte Nachrichteninterceptoren für alle Nachrichten hinzufügen können, die einen WCF-Client durchlaufen.
Außerdem gibt es eine Reihe weiterer Eigenschaften, die die Clientvertragsinformationen abrufen:
Wenn es sich bei dem WCF-Client um einen WCF-Duplexclient handelt, rufen die folgenden Eigenschaften auch Rückrufinformationen des WCF-Clients ab.
Wenn Sie die Ausführung des WCF-Clients über einen gesamten WCF-Client ausdehnen möchten, prüfen Sie die in der ClientRuntime-Klasse verfügbaren Eigenschaften. So können Sie ermitteln, ob durch das Ändern einer Eigenschaft oder das Implementieren einer Schnittstelle und Hinzufügen zu einer Eigenschaft die gewünschte Funktionalität gewährleistet wird. 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.
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). 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. Weitere Informationen: Konfigurieren und Erweitern der Laufzeit mit Verhalten.
Beispiele, die das Abfangen über einen WCF-Client hinweg veranschaulichen, finden Sie unter Vorgehensweise: Überprüfen oder Ändern von Nachrichten auf dem Client.
Verwenden der ClientOperation-Klasse
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. (Um das Clientlaufzeitverhalten für alle Nachrichten in einem Vertrag zu ändern, verwenden Sie die ClientRuntime-Klasse.)
Verwenden Sie die Operations-Eigenschaft, um das ClientOperation-Objekt zu suchen, das einen bestimmten Dienstvorgang darstellt. Die folgenden Eigenschaften ermöglichen Ihnen, benutzerdefinierte Objekte in das WCF-Clientsystem einzufügen:
Verwenden Sie die Formatter-Eigenschaft, um eine benutzerdefinierte IClientMessageFormatter-Implementierung für einen Vorgang einzufügen oder das aktuelle Formatierungsprogramm zu ändern.
Verwenden Sie die ParameterInspectors-Eigenschaft, um eine benutzerdefinierte IParameterInspector-Implementierung einzufügen oder die aktuelle Implementierung zu ändern.
Mit den folgenden Eigenschaften können Sie das System in Interaktion mit dem Formatierungsprogramm und benutzerdefinierten Parameterinspektoren ändern:
Verwenden Sie die SerializeRequest-Eigenschaft, um die Serialisierung einer ausgehenden Nachricht zu steuern.
Verwenden Sie die DeserializeReply-Eigenschaft, um die Deserialisierung einer eingehenden Nachricht zu steuern.
Verwenden Sie die Action-Eigenschaft, um die WS-Adressierungsaktion der Anforderungsnachricht zu steuern.
Verwenden Sie BeginMethod und EndMethod, um anzugeben, welche WCF-Clientmethoden einem asynchronen Vorgang zugeordnet werden.
Verwenden Sie die FaultContractInfos-Eigenschaft, um eine Auflistung der angegebenen Typen abzurufen, die als Detailtyp in SOAP-Fehlern erscheinen können.
Verwenden Sie die IsInitiating-Eigenschaft und die IsTerminating-Eigenschaft, um zu steuern, ob eine Sitzung initiiert bzw. abgebrochen wird, wenn der Vorgang aufgerufen wird.
Verwenden Sie die IsOneWay-Eigenschaft, um zu steuern, ob es sich bei dem Vorgang um einen unidirektionalen Vorgang handelt.
Verwenden Sie die Parent-Eigenschaft, um das darin enthaltene ClientRuntime-Objekt zu ermitteln.
Verwenden Sie die Name-Eigenschaft, um den Namen des Vorgangs abzurufen.
Verwenden Sie die SyncMethod-Eigenschaft, um zu steuern, welche Methode dem Vorgang zugeordnet wird.
Wenn Sie die Ausführung des WCF-Clients über nur einen Dienstvorgang ausdehnen möchten, prüfen Sie die in der ClientOperation-Klasse verfügbaren Eigenschaften. So können Sie ermitteln, ob durch das Ändern einer Eigenschaft oder das Implementieren einer Schnittstelle und Hinzufügen zu einer Eigenschaft die gewünschte Funktionalität gewährleistet wird. 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. In diesem Verhalten können Sie dann die ClientRuntime-Eigenschaft ändern, um sie Ihren Anforderungen anzupassen.
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. Weitere Informationen: Konfigurieren und Erweitern der Laufzeit mit Verhalten.
Um das benutzerdefinierte Verhalten der Konfiguration zu verwenden, installieren Sie das Verhalten mit einem benutzerdefinierten Verhaltenskonfigurationsabschnitts-Handler. Sie können auch das Verhalten installieren, indem Sie ein benutzerdefiniertes Attribut erstellen.
Beispiele, die das Abfangen über einen WCF-Client hinweg veranschaulichen, finden Sie unter Vorgehensweise: Überprüfen oder Ändern von Parametern.