Extension de clients
Dans une application appelante, la couche de modèle de service est chargée de traduire les appels de méthode du code d'application en messages sortants, de les envoyer vers les canaux sous-jacents, de retraduire les résultats en valeurs de retour et paramètres de sortie dans le code d'application, et de retourner de nouveau les résultats à l'appelant. Les extensions de modèle de service modifient ou implémentent le comportement et les fonctionnalités d’exécution ou de communication qui impliquent des fonctionnalités de répartiteur ou client, des comportements personnalisés, l’interception de messages et de paramètres, ainsi que d’autres fonctionnalités d’extensibilité.
Cette rubrique décrit comment utiliser les classes ClientRuntime et ClientOperation dans une application de service Windows Communication Foundation (WCF) afin de modifier le comportement d’exécution par défaut d’un client WCF, ou d’intercepter ou de modifier des messages, des paramètres ou des valeurs de retour avant ou après leur échange (envoi ou récupération) avec la couche du 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 l’exécution du client, consultez Configuration et extension du runtime avec des comportements.
Clients
Sur un client, un canal ou objet client WCF convertit des appels de méthode en messages sortants et messages entrants aux résultats de l’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 ce point de terminaison, et les fonctionnalités au niveau de l’opération. Lorsqu'une application appelle une opération, ClientOperation traduit les objets sortants en message, traite des intercepteurs, confirme que l'appel sortant est conforme au contrat cible, et transmet le message sortant à ClientRuntime, qui est chargé de créer et de gérer des canaux sortants (et canaux entrants dans le cas de services duplex), de gérer le traitement des messages sortants supplémentaires (tel que la modification de l'en-tête), de traiter des intercepteurs de message dans les deux directions, et de router des appels duplex entrants vers l'objet DispatchRuntime côté client approprié. ClientOperation et ClientRuntime fournissent tous deux des services similaires lorsque les messages (y compris les erreurs) sont retournés au client.
Ces deux classes d’exécution constituent l’extension principale permettant de personnaliser le traitement des canaux et objets 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 classe ClientOperation 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 d’exécution du client, consultez Configuration et extension du runtime avec des comportements.
Scénarios
L'extension du système client peut être justifiée pour un certain nombre de raisons, dont les suivantes :
Validation personnalisée des messages. Un utilisateur souhaite s'assurer qu'un message est valide pour un schéma spécifique. Cela peut être accompli en implémentant l'interface IClientMessageInspector et en assignant l'implémentation à la propriété MessageInspectors. Pour obtenir des exemples, consultez Comment : Inspecter ou modifier des messages sur le client et Comment : Inspecter ou modifier des messages sur le client.
Enregistrement personnalisé des messages. Un utilisateur souhaite inspecter et enregistrer des jeux de messages d'application qui transitent par un point de terminaison. Cela peut également être accompli à l'aide des interfaces de l'intercepteur de messages.
Transformations personnalisées des messages. Plutôt que de modifier le code d'application, l'utilisateur souhaite appliquer certaines transformations au message dans l'exécution (pour le contrôle de version par exemple). Cela peut, à nouveau, être accompli à l'aide des interfaces de l'intercepteur de messages.
Modèle personnalisé de données. Un utilisateur souhaite disposer d’un modèle de données ou de sérialisation autre que ceux pris en charge par défaut dans (à savoir, les objets System.Runtime.Serialization.DataContractSerializer, System.Xml.Serialization.XmlSerializer et System.ServiceModel.Channels.Message). Cela peut être accompli en implémentant les interfaces du formateur de messages. Pour plus d'informations, consultez System.ServiceModel.Dispatcher.IClientMessageFormatter et la propriété ClientOperation.Formatter.
Validation personnalisée des paramètres. Un utilisateur souhaite que les paramètres typés soient valides (par opposition à XML). Cela peut être accompli à l'aide des interfaces de l'inspecteur de paramètres. Pour obtenir un exemple, consultez Comment : Inspecter ou modifier des paramètres ou Validation du client.
Utilisation de la classe ClientRuntime
La classe ClientRuntime est un point d’extensibilité auquel vous pouvez ajouter des objets d’extension qui interceptent des messages et étendent le comportement du client. Les objets d'interception peuvent traiter tous les messages d'un contrat spécifique, traiter uniquement les messages de certaines opérations, exécuter l'initialisation de canal personnalisée et implémenter un autre comportement d'application cliente personnalisé.
La propriété CallbackDispatchRuntime retourne l'objet d'exécution de répartition pour les clients de rappel initiés par le service.
La propriété OperationSelector accepte un objet de sélecteur d'opération personnalisé.
La propriété ChannelInitializers permet d'ajouter un initialiseur de canal qui peut inspecter ou modifier le canal client.
La propriété Operations obtient une collection d’objets ClientOperation auxquels vous pouvez ajouter des intercepteurs de messages personnalisés qui fournissent les fonctionnalités spécifiques aux messages de cette opération.
La propriété ManualAddressing permet à une application de désactiver certains en-têtes d'adressage automatique afin de contrôler directement l'adressage.
La propriété Via affecte la valeur de la destination du message au niveau du transport afin de prendre en charge les intermédiaires et d'autres scénarios.
La propriété MessageInspectors obtient une collection d’objets IClientMessageInspector auxquels vous pouvez ajouter des intercepteurs de messages personnalisés pour tous les messages transmis via un client WCF.
Par ailleurs, un certain nombre d'autres propriétés récupèrent les informations de contrat :
Si le client WCF est un client WCF duplex, les propriétés suivantes récupèrent également les informations sur le client WCF de rappel :
Pour étendre l’exécution de client WCF sur l’ensemble d’un client WCF, consultez les propriétés disponibles sur la classe ClientRuntime afin de déterminer si la modification d’une propriété ou l’implémentation d’une interface et l’ajout de celle-ci à une propriété crée les fonctionnalités que vous recherchez. Après avoir choisi l'extension spécifique à générer, insérez-la dans la propriété ClientRuntime appropriée en implémentant un comportement client permettant d'accéder à la classe ClientRuntime en cas d'appel.
Vous pouvez insérer des objets d'extension personnalisés dans une collection à l'aide d'un comportement d'opération (objet qui implémente IOperationBehavior), d'un comportement de contrat (objet qui implémente IContractBehavior) ou d'un comportement de point de terminaison (objet qui implémente IEndpointBehavior). L'objet de comportement installé est ajouté à la collection appropriée de comportements par programme ou de façon déclarative (en implémentant un attribut personnalisé), ou en implémentant un objet BehaviorExtensionElement personnalisé pour que le comportement soit inséré à 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 dans un client WCF, consultez Comment : Inspecter ou modifier des messages sur le client.
Utilisation de la classe ClientOperation
La classe ClientOperation correspond à l’emplacement des modifications d’exécution du client et au point d’insertion des 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 classe ClientRuntime.)
Utilisez la propriété Operations 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 :
La propriété Formatter permet d'insérer une implémentation IClientMessageFormatter personnalisée pour une opération ou de modifier le formateur actuel.
La propriété ParameterInspectors permet d'insérer une implémentation IParameterInspector personnalisée ou de modifier l'implémentation actuelle.
Les propriétés suivantes vous permettent de modifier le système dans l'interaction à l'aide du formateur et des inspecteurs de paramètre personnalisés :
La propriété SerializeRequest permet de contrôler la sérialisation d'un message sortant.
La propriété DeserializeReply permet de contrôler la désérialisation d’un message entrant.
La propriété Action permet de contrôler l'action WS-Addressing du message de demande.
Les propriétés BeginMethod et EndMethod permettent de spécifier les méthodes clientes WCF qui sont associées à une opération asynchrone.
La propriété FaultContractInfos permet d’obtenir une collection contenant les types qui peuvent apparaître dans les erreurs SOAP comme type de détail.
Les propriétés IsInitiating et IsTerminating permettent respectivement de contrôler si une session est initiée ou détruite, lorsque l'opération est appelée.
La propriété IsOneWay permet de contrôler si l'opération est monodirectionnelle.
La propriété Parent permet d'obtenir l'objet contenant ClientRuntime.
La propriété Name permet d'obtenir le nom de l'opération.
La propriété SyncMethod permet de contrôler la méthode mappée à l'opération.
Pour étendre l’exécution de client WCF sur une seule opération de service, consultez les propriétés disponibles sur la classe ClientOperation afin de déterminer si la modification d’une propriété ou l’implémentation d’une interface et l’ajout de celle-ci à une propriété crée les fonctionnalités que vous recherchez. Après avoir choisi l'extension spécifique à générer, insérez-la dans la propriété ClientOperation appropriée en implémentant un comportement client permettant d'accéder à la classe ClientOperation en cas d'appel. Dans ce comportement, vous pouvez ensuite modifier la propriété ClientRuntime en fonction de vos besoins.
En général, 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 de contrat en localisant le OperationDescription d'une opération spécifique et en joignant le comportement à cet emplacement. Pour plus d’informations, consultez Configuration et extension du runtime avec des comportements.
Pour utiliser votre comportement personnalisé à partir de la configuration, installez-le à l'aide d'un gestionnaire de section de configuration de comportement personnalisé. Vous pouvez également l'installer en créant un attribut personnalisé.
Pour obtenir des exemples illustrant l’interception dans un client WCF, consultez Comment : Inspecter ou modifier des paramètres.