Remarque
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.
Cette rubrique explique comment créer des encodeurs personnalisés.
Dans Windows Communication Foundation (WCF), vous utilisez une liaison pour spécifier comment transférer des données sur un réseau entre des points de terminaison. Une liaison est constituée d’une séquence d’éléments de liaison. Une liaison inclut des éléments de liaison de protocole facultatifs tels que la sécurité, un élément de liaison d’encodeur de message requis et un élément de liaison de transport requis. Un encodeur de message est représenté par un élément de liaison d’encodage de message. Trois encodeurs de message sont inclus dans WCF : Binaire, Mécanisme d’optimisation de la transmission des messages (MTOM) et Texte.
Un élément de liaison d’encodage de message sérialise un sortant Message et le transmet au transport, ou reçoit la forme sérialisée d’un message du transport et le transmet à la couche de protocole le cas échéant, ou à l’application, s’il n’est pas présent.
Les encodeurs de messages transforment Message des instances vers et à partir d’une représentation filaire. Bien que les encodeurs soient décrits comme assis au-dessus de la couche de transport dans la pile de canaux, ils résident à l’intérieur de la couche de transport. Les transports (par exemple HTTP) mettent en forme le message en fonction des exigences de la norme de transport. Les encodeurs (par exemple Text Xml) encodent simplement le message.
Lors de la connexion à un client ou serveur préexistant, vous n’avez peut-être pas le choix d’utiliser un encodage de message particulier. Toutefois, les services WCF peuvent être rendus accessibles via plusieurs points de terminaison, chacun avec un encodeur de message différent. Lorsqu’un encodeur unique ne couvre pas l’ensemble de l’audience de votre service, envisagez d’exposer votre service sur plusieurs points de terminaison. Les applications clientes peuvent ensuite choisir le point de terminaison qui leur convient le mieux. L’utilisation de plusieurs points de terminaison vous permet de combiner les avantages de différents encodeurs de messages avec d’autres éléments de liaison.
Encodeurs fournis par le système
WCF fournit plusieurs liaisons fournies par le système conçues pour couvrir les scénarios d’application les plus courants. Chacune de ces liaisons combine un transport, un encodeur de message et d’autres options (sécurité, par exemple). Ce sujet décrit comment étendre les encodeurs de messages Text, Binary et MTOM inclus dans WCF, ou comment créer votre propre encodeur personnalisé. L’encodeur de sms prend en charge un encodage XML brut ainsi que des encodages SOAP. Le mode d’encodage XML brut de l’encodeur de message texte est appelé encodeur POX (« Plain Old XML ») pour le distinguer de l’encodage SOAP basé sur du texte.
Pour plus d’informations sur les combinaisons d’éléments de liaison fournis par les liaisons fournies par le système, consultez la section correspondante dans Choisir un transport.
Utilisation des encodeurs System-Provided
Un encodage est ajouté à une liaison à l’aide d’une classe dérivée de MessageEncodingBindingElement.
WCF fournit les types d’éléments de liaison suivants dérivés de la MessageEncodingBindingElement classe qui peuvent fournir l’encodage MTOM (Text, Binary And Message Transmission Optimization Mechanism) :
TextMessageEncodingBindingElement: le plus interopérable, mais l’encodeur le moins efficace pour les messages XML. Un service web ou un client de service web peut généralement comprendre du code XML textuel. Toutefois, la transmission de grands blocs de données binaires en tant que texte n’est pas efficace.
BinaryMessageEncodingBindingElement: représente l’élément de liaison qui spécifie l’encodage de caractères et le contrôle de version des messages utilisés pour les messages XML binaires. Cela est le plus efficace des options d’encodage, mais le moins interopérable, car il n’est pris en charge que par les points de terminaison WCF.
MtomMessageEncodingBindingElement: représente l’élément de liaison qui spécifie l’encodage de caractères et le contrôle de version des messages utilisés pour un message à l’aide d’un encodage MTOM (Message Transmission Optimization Mechanism). MTOM est une technologie efficace pour transmettre des données binaires dans des messages WCF. L’encodeur MTOM tente d’équilibrer l’efficacité et l’interopérabilité. L’encodage MTOM transmet la plupart des données XML sous forme textuelle, mais optimise les grands blocs de données binaires en les transmettant as-is, sans conversion en texte.
L’élément de liaison crée un fichier binaire, MTOM ou du texte MessageEncoderFactory. L'usine crée une instance binaire, MTOM ou texte MessageEncoderFactory. En règle générale, il n’existe qu’une seule instance. Toutefois, si des sessions sont utilisées, un encodeur différent peut être fourni à chaque session. L’encodeur binaire l’utilise pour coordonner les dictionnaires dynamiques (voir Infrastructure XML).
Les méthodes ReadMessage et WriteMessage constituent le cœur des encodeurs. Les méthodes fournissent la lecture d’un message à partir d’un flux ou d’un Byte tableau. Les tableaux d’octets sont utilisés lorsque le transport fonctionne en mode mis en mémoire tampon. Les messages sont toujours écrits dans des flux de données. Si le transport doit mettre en mémoire tampon le message, il fournit un flux qui effectue la mise en mémoire tampon.
Le reste des membres utilisent le contenu de support, les types de média et MessageVersion. Le transport appelle ces méthodes d’encodeur pour tester si le message entrant peut être décodé par celui-ci ou pour déterminer si le message sortant est valide pour cet encodeur.
Chacune des trois implémentations d’encodeur ajoute des propriétés pertinentes pour les encodages spécifiques et est entièrement configurable. Les encodeurs exposent également des quotas de lecteur qui ont des valeurs par défaut sécurisées. Consultez l’infrastructure XML pour une discussion sur les quotas.
Fonctionnalités des encodeurs System-Provided
Il existe plusieurs fonctionnalités fournies par les encodeurs fournis par le système.
Regroupement
Chacune des implémentations de l’encodeur tente de regrouper autant que possible. La réduction des allocations est un moyen clé d’améliorer les performances du code managé. Pour effectuer ce regroupement, les implémentations utilisent la SynchronizedPool classe. Le fichier C# contient une description des optimisations supplémentaires utilisées par cette classe.
XmlDictionaryReader et XmlDictionaryWriter les instances sont mises en pool et réinitialisées pour empêcher l’allocation de nouvelles instances pour chaque message. Pour les lecteurs, un rappel OnClose récupère le lecteur lorsque Close() est appelé. L’encodeur recycle également certains objets d’état de message utilisés lors de la construction de messages. Les tailles de ces pools sont configurables par les propriétés MaxReadPoolSize et MaxWritePoolSize de chacune des trois classes dérivées de MessageEncodingBindingElement.
Encodage binaire
Lorsque l’encodage binaire utilise des sessions, la chaîne de dictionnaire dynamique doit être communiquée au destinataire du message. Pour ce faire, préfixez le message avec les chaînes de dictionnaire dynamique. Le récepteur supprime les chaînes, les ajoute à la session et traite le message. La transmission correcte des chaînes de dictionnaire nécessite la mise en mémoire tampon du transport.
Les chaînes sont ajoutées au message par une méthode interne AddSessionInformationToMessage . Il ajoute les chaînes en UTF-8 au devant du message précédé de leur longueur. L’en-tête de dictionnaire entier est ensuite précédé de la longueur de ses données. L’opération inverse est effectuée par une méthode interne ExtractSessionInformationFromMessage .
Outre le traitement des clés de dictionnaire dynamiques, les messages en mémoire tampon liés à des sessions sont reçus d'une manière unique. Au lieu de créer un lecteur sur le document et de le traiter, l’encodeur binaire utilise la classe interne MessagePatterns pour déconstructer le flux binaire. L’idée est que la plupart des messages ont un certain ensemble d’en-têtes qui s’affichent dans un certain ordre lorsqu’ils sont générés par WCF. Le système de modèle sépare le message en fonction de ce qu’il attend. S’il réussit, il initialise un MessageHeaders objet sans analyser le code XML. Si ce n’est pas le cas, il revient à la méthode standard.
Encodage MTOM
La MtomMessageEncodingBindingElement classe a une propriété de configuration supplémentaire appelée MaxBufferSize. Cela place une limite supérieure sur la quantité de données qu’il est autorisé à mettre en mémoire tampon pendant le processus de lecture d’un message. Le jeu d’informations XML (Infoset) ou d’autres parties MIME peut être mis en mémoire tampon pour réassembler toutes les parties MIME dans un seul message.
Pour fonctionner correctement avec HTTP, la classe d’encodeur de message MTOM interne fournit certaines API internes pour GetContentType (qui est également interne) et WriteMessage, qui est publique et peut être substituée. Une communication supplémentaire doit se produire pour garantir que les valeurs dans les en-têtes HTTP sont d’accord avec les valeurs des en-têtes MIME.
En interne, l’encodeur de message MTOM utilise les lecteurs de texte de WCF et est similaire à l’encodeur de texte. La principale différence est qu’il optimise les grands blocs de binaires ou « objets blob binaires » en ne les convertissant pas en encodage base 64 avant d’être incorporés dans les octets de message. À la place, ces BLOB restent extraits et référencés comme des pièces jointes MIME.
Écriture de votre propre encodeur
Pour implémenter votre propre encodeur de message personnalisé, vous devez fournir des implémentations personnalisées des classes de base abstraites suivantes :
La conversion de la représentation en mémoire d’un message en une représentation pouvant être écrite dans un flux est encapsulée dans la MessageEncoder classe, qui sert de fabrique pour les lecteurs XML et les enregistreurs XML qui prennent en charge des types spécifiques d’encodages XML.
Les méthodes clés de cette classe que vous devez remplacer sont les suivantes :
WriteMessage qui prend un MessageEncodingBindingElement objet et l’écrit dans un Stream objet.
ReadMessage qui prend un Stream objet et une taille d’en-tête maximale et retourne un Message objet.
Il s’agit du code que vous écrivez dans ces méthodes qui gère la conversion entre le protocole de transport standard et votre encodage personnalisé.
Ensuite, vous devez coder une classe de fabrique qui crée votre encodeur personnalisé. Substituez Encoder pour retourner une instance de votre MessageEncoder personnalisé.
Puis connectez votre MessageEncoderFactory personnalisé à la pile d’élément de liaison utilisée pour configurer le service ou le client en substituant la méthode CreateMessageEncoderFactory pour retourner une instance de cette fabrique.
Il existe deux exemples fournis avec WCF qui illustrent ce processus avec l’exemple de code : Custom Message Encoder : Custom Text Encoder et Custom Message Encoder : Compression Encoder.