Notes
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de vous connecter ou de modifier des répertoires.
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de modifier des répertoires.
Dans une application appelante, la couche modèle de service est chargée de traduire les appels de méthode dans le code de l’application en messages sortants, de les envoyer vers les canaux sous-jacents, de traduire les résultats en valeurs de retour et en paramètres sortants dans le code de l’application, et de renvoyer les résultats à l’appelant. Les extensions de modèle de service modifient ou implémentent un comportement d’exécution ou de communication et des fonctionnalités impliquant des fonctionnalités client ou répartiteur, des comportements personnalisés, des interceptions de messages et de paramètres et d’autres fonctionnalités d’extensibilité.
Cette rubrique explique comment utiliser les classes ClientRuntime et ClientOperation dans une application cliente Windows Communication Foundation (WCF) pour modifier le comportement par défaut d'exécution d'un client WCF ou pour intercepter ou modifier les messages, les paramètres ou les valeurs de retour avant ou après leur envoi ou récupération depuis la couche de canal. Pour plus d’informations sur l’extension du runtime de service, consultez Extension des répartiteurs. Pour plus d’informations sur les comportements qui modifient et insèrent des objets de personnalisation dans le runtime client, consultez Configuration et extension du runtime avec des comportements.
Clients
Sur un client, un objet client WCF ou un canal client convertit les appels de méthode en messages sortants et les messages entrants en résultats d’opération retournés à l’application appelante. (Pour plus d’informations sur les types de clients, consultez Architecture du client WCF.)
Les types de clients WCF ont des types d’exécution qui gèrent cette fonctionnalité au niveau du point de terminaison et de l’opération. Lorsqu’une application appelle une opération, ClientOperation traduit les objets sortants en un message, traite les intercepteurs, confirme que l’appel sortant est conforme au contrat cible, et remet le message sortant au ClientRuntime, qui est responsable de la création et de la gestion des canaux sortants (et des canaux entrants dans le cas des services en duplex), de la gestion du traitement supplémentaire des messages sortants (comme la modification des en-têtes), du traitement des intercepteurs de messages dans les deux sens, et du routage des appels en duplex entrants vers l’objet DispatchRuntime approprié côté client. Les ClientOperation et ClientRuntime fournissent tous deux des services similaires lorsque les messages (y compris les erreurs) sont retournés au client.
Ces deux classes runtime sont l’extension principale pour personnaliser le traitement des objets et canaux clients WCF. La classe ClientRuntime permet aux utilisateurs d'intercepter et d'étendre l'exécution du client sur l'ensemble des messages du contrat. La ClientOperation classe permet aux utilisateurs d’intercepter et d’étendre l’exécution du client pour tous les messages d’une opération donnée.
La modification des propriétés ou l'insertion de personnalisations sont effectuées en utilisant des comportements de contrat, de point de terminaison et d'opération. Pour plus d’informations sur l’utilisation de ces types de comportements pour effectuer des personnalisations du runtime client, consultez Configuration et extension du runtime avec des comportements.
Scénarios
Il existe plusieurs raisons d’étendre le système client, notamment :
Validation de message personnalisée. Un utilisateur peut vouloir appliquer qu’un message est valide pour un schéma donné. Pour ce faire, implémentez l’interface IClientMessageInspector et affectez l’implémentation à la MessageInspectors propriété. Pour obtenir des exemples, consultez Comment : inspecter ou modifier des messages sur le client et Comment : inspecter ou modifier des messages sur le client.
Journalisation des messages personnalisée. Un utilisateur peut souhaiter inspecter et consigner un ensemble de messages d’application qui transitent par un point de terminaison. Cela peut également être effectué avec les interfaces d’intercepteur de message.
Transformations de message personnalisées. Au lieu de modifier le code de l’application, l’utilisateur peut souhaiter appliquer certaines transformations au message dans le runtime (par exemple, pour le contrôle de version). Cette opération peut être effectuée, à nouveau, avec les interfaces d’intercepteur de message.
Modèle de données personnalisé. Un utilisateur peut vouloir un modèle de données ou de sérialisation autre que ceux pris en charge par défaut dans WCF (à savoir, les objets System.Runtime.Serialization.DataContractSerializer, System.Xml.Serialization.XmlSerializer et System.ServiceModel.Channels.Message). Pour ce faire, implémentez les interfaces du formateur de message. Pour plus d’informations, consultez System.ServiceModel.Dispatcher.IClientMessageFormatter et la ClientOperation.Formatter propriété.
Validation des paramètres personnalisés. Un utilisateur peut vouloir s'assurer que les paramètres typés sont valides, contrairement au XML. Cette opération peut être effectuée à l’aide des interfaces de l’inspecteur de paramètres. Pour obtenir un exemple, consultez Comment : inspecter ou modifier des paramètres ou la validation du client.
Utilisation de la classe ClientRuntime
La ClientRuntime classe est un point d’extensibilité auquel vous pouvez ajouter des objets d’extension qui interceptent les messages et étendent le comportement du client. Les objets d’interception peuvent traiter tous les messages d’un contrat particulier, traiter uniquement les messages pour des opérations particulières, effectuer une initialisation de canal personnalisé et implémenter d’autres comportements d’application cliente personnalisée.
La propriété CallbackDispatchRuntime retourne l'objet d'exécution de répartition pour les clients de rappel initiés par le service.
La OperationSelector propriété accepte un objet sélecteur d’opération personnalisé.
La ChannelInitializers propriété active l’ajout d’un initialiseur de canal qui peut inspecter ou modifier le canal client.
La Operations propriété obtient une collection d’objets auxquels vous pouvez ajouter des intercepteurs de ClientOperation messages personnalisés qui fournissent des fonctionnalités spécifiques aux messages de cette opération.
La ManualAddressing propriété permet à une application de désactiver certains en-têtes d’adressage automatiques pour contrôler directement l’adressage.
La Via propriété définit la valeur de la destination du message au niveau du transport pour prendre en charge les intermédiaires et d’autres scénarios.
La MessageInspectors propriété obtient une collection d’objets auxquels vous pouvez ajouter des intercepteurs de IClientMessageInspector messages personnalisés pour tous les messages voyageant via un client WCF.
En outre, il existe plusieurs autres propriétés qui récupèrent les informations de contrat :
Si le client WCF est un client duplex, les propriétés suivantes récupèrent également les informations du client WCF callback :
Pour étendre l’exécution du client WCF sur un client WCF entier, passez en revue les propriétés disponibles sur la ClientRuntime classe pour déterminer si la modification d’une propriété ou l’implémentation d’une interface et l’ajout à une propriété crée les fonctionnalités que vous recherchez. Une fois que vous avez choisi une extension particulière à générer, insérez votre extension dans la propriété appropriée ClientRuntime en implémentant un comportement client qui fournit l’accès à la ClientRuntime classe lorsqu’elle est appelée.
Vous pouvez insérer des objets d’extension personnalisés dans une collection à l’aide d’un comportement d’opération (un objet qui implémente IOperationBehavior), d’un comportement de contrat (un objet qui implémente IContractBehavior) ou d’un comportement de point de terminaison (un objet qui implémente IEndpointBehavior). L’objet de comportement d’installation est ajouté à la collection appropriée de comportements par programme, de manière déclarative (en implémentant un attribut personnalisé) ou en implémentant un objet personnalisé BehaviorExtensionElement pour permettre l’insertion du comportement à l’aide d’un fichier de configuration d’application. Pour plus d’informations, consultez Configuration et extension du runtime avec des comportements.
Pour obtenir des exemples illustrant l’interception sur un client WCF, consultez Guide pratique pour inspecter ou modifier des messages sur le client.
Utilisation de la classe ClientOperation
La ClientOperation classe est l’emplacement des modifications au moment de l’exécution du client et du point d’insertion pour les extensions personnalisées qui sont limitées à une seule opération de service. (Pour modifier le comportement d’exécution du client pour tous les messages d’un contrat, utilisez la ClientRuntime classe.)
Utilisez la Operations propriété pour localiser l’objet ClientOperation qui représente une opération de service particulière. Les propriétés suivantes vous permettent d’insérer des objets personnalisés dans le système client WCF :
Utilisez la Formatter propriété pour insérer une implémentation personnalisée IClientMessageFormatter pour une opération ou modifier le formateur actuel.
Utilisez la ParameterInspectors propriété pour insérer une implémentation personnalisée IParameterInspector ou modifier l’implémentation actuelle.
Les propriétés suivantes vous permettent de modifier le système en interaction avec le formateur et les inspecteurs de paramètres personnalisés.
Utilisez la SerializeRequest propriété pour contrôler la sérialisation d’un message sortant.
Utilisez la DeserializeReply propriété pour contrôler la désérialisation d’un message entrant.
Utilisez la Action propriété pour contrôler l’action WS-Addressing du message de requête.
Utilisez BeginMethod et EndMethod pour spécifier les méthodes clientes WCF associées à une opération asynchrone.
Utilisez la FaultContractInfos propriété pour obtenir une collection qui contient les types qui peuvent apparaître dans les erreurs SOAP comme type de détail.
Utilisez les propriétés IsInitiating et IsTerminating pour contrôler respectivement si une session est lancée ou est détruite lorsque l’opération est appelée.
Utilisez la IsOneWay propriété pour contrôler si l’opération est une opération unidirectionnelle.
Utilisez la Parent propriété pour obtenir l’objet conteneur ClientRuntime .
Utilisez la Name propriété pour obtenir le nom de l’opération.
Utilisez la propriété SyncMethod pour contrôler quelle méthode est associée à l’opération.
Pour étendre l’exécution du client WCF sur une seule opération de service, passez en revue les propriétés disponibles sur la ClientOperation classe pour déterminer si la modification d’une propriété ou l’implémentation d’une interface et son ajout à une propriété crée les fonctionnalités que vous recherchez. Une fois que vous avez choisi une extension particulière à générer, insérez votre extension dans la propriété appropriée ClientOperation en implémentant un comportement client qui fournit l’accès à la ClientOperation classe lorsqu’elle est appelée. Dans ce comportement, vous pouvez ensuite modifier la ClientRuntime propriété pour répondre à vos besoins.
En règle générale, l’implémentation d’un comportement d’opération (objet qui implémente l’interface IOperationBehavior ) suffit, mais vous pouvez également utiliser des comportements de point de terminaison et des comportements de contrat pour accomplir la même chose en recherchant l’opération OperationDescription particulière et en attachant le comportement là-bas. Pour plus d’informations, consultez Configuration et extension du runtime avec des comportements.
Pour utiliser votre comportement personnalisé à partir de la configuration, installez votre comportement à l’aide d’un gestionnaire de section de configuration de comportement personnalisé. Vous pouvez également installer votre comportement en créant un attribut personnalisé.
Pour obtenir des exemples illustrant l’interception sur un client WCF, consultez Guide pratique pour inspecter ou modifier des paramètres.