Prise en charge du .NET Framework pour les formats SOAP

Article
02/27/2011

Cette rubrique est spécifique à une technologie existante. Les services Web XML et les clients du service Web XML doivent à présent être créés à l'aide de Windows Communication Foundation.

Au lieu de fabriquer à la main un document WSDL, un développeur qui crée un service Web pour ASP.NET peut spécifier ces formats SOAP en appliquant des attributs à des méthodes de service Web individuelles ou à des classes de service Web entières. Si un développeur ne spécifie pas ces attributs, les formats SOAP par défaut sont utilisés.

Si vous développez un service Web sur la base d'un document WSDL existant, vous pouvez exécuter l'outil Wsdl.exe avec l'option /server pour générer une classe de service Web abstraite dont les valeurs d'attribut appropriées sont définies automatiquement.

Sans l'option /server, Wsdl.exe produit une classe proxy de client qui affecte aux attributs de mise en forme SOAP pertinents les valeurs appropriées pour communiquer avec le service Web décrit par le document WSDL d'entrée. Une classe proxy de client utilise la plupart des mêmes attributs que ceux pouvant être spécifiés sur le serveur. Normalement, un développeur n'a pas besoin d'ajouter ou de modifier manuellement ces attributs dans la classe proxy de client car normalement le client est généré par Wsdl.exe pour assurer sa conformité avec le contrat de service spécifié par le document WSDL.

Le tableau suivant montre les choix de mise en forme pris en charge par les clients et services Web créés à l'aide d'ASP.NET et du .NET Framework, avec les attributs qui accomplissent chaque combinaison spécifique. Les attributs avec un suffixe Service peuvent être appliqués à une classe qui implémente un service Web (pas une classe proxy de client) pour définir le style de mise en forme par défaut pour les méthodes de service Web dans la classe. Les attributs avec un suffixe Method peuvent être appliqués soit à une méthode de service Web, soit à une méthode d'une classe proxy de client qui appelle une méthode de service Web. Les détails de chaque combinaison sont traités dans les paragraphes suivants.

Mise en forme de paramètre (use)	Mise en forme de corps SOAP (style) pour les messages SOAP basés sur document	Mise en forme de corps SOAP (style) pour les messages SOAP basés sur RPC conformément à SOAP 1.1 Section 7s
Literal — basé sur un schéma XSD pour chaque paramètre	SoapDocumentMethod ou SoapDocumentService Use=Literal Il s'agit de la valeur par défaut.	SoapRpcMethod ou SoapRpcService Use=Literal
Encoded - règles d'encodage SOAP 1.1 Section 5	SoapDocumentMethod ou SoapDocumentService Use=Encoded	SoapRpcMethod ou SoapRpcService Use=Encoded Il s'agit de la valeur par défaut.

Mise en forme de paramètre (use)

Mise en forme de corps SOAP (style) pour les messages SOAP basés sur document

Mise en forme de corps SOAP (style) pour les messages SOAP basés sur RPC conformément à SOAP 1.1 Section 7s

Literal — basé sur un schéma XSD pour chaque paramètre

SoapDocumentMethod ou SoapDocumentService

Use=Literal

Il s'agit de la valeur par défaut.

SoapRpcMethod ou SoapRpcService

Use=Literal

Encoded - règles d'encodage SOAP 1.1 Section 5

SoapDocumentMethod ou SoapDocumentService

Use=Encoded

SoapRpcMethod ou SoapRpcService

Use=Encoded

Il s'agit de la valeur par défaut.

Remarque :
Les noms réels de l'attribut utilisent le suffixe Attribute. Dans le code source, les noms peuvent être abrégés, comme indiqué dans le tableau précédent.

Contrôle de la mise en forme globale du corps SOAP

Pour style, qui contrôle si le moteur d'exécution de service Web applique les conventions RPC ou défère aux documents XML, le choix par défaut dans un service Web ASP.NET est document, pas RPC.

Le style du document peut être spécifié explicitement en appliquant l'attribut SoapDocumentMethodAttribute à une méthode de service Web ou une méthode de proxy client, ou en appliquant l'attribut SoapDocumentServiceAttribute à une classe de service Web. Le style PRC peut être spécifié explicitement en appliquant l'attribut SoapRpcMethodAttribute à une méthode de service Web ou une méthode de proxy client, ou en appliquant l'attribut SoapRpcServiceAttribute à une classe de service Web. Pour un service, un attribut de niveau méthode remplace un attribut de niveau classe.

Ces mêmes attributs jouent un rôle pour déterminer la mise en forme des paramètres et des valeurs de retour, comme indiqué plus loin dans cette rubrique. Ils jouent également un rôle pour déterminer si un élément « wrapper » est généré automatiquement pendant l'exécution pour contenir les paramètres ou la valeur de retour. Pour plus d'informations, consultez Comment : contrôler si les paramètres de méthode de service Web sont joints dans un élément supplémentaire.

Pour plus d'informations sur le sujet suivant l'application de ces attributs, consultez Comment : contrôler la mise en forme globale du corps SOAP pour une méthode de service Web.

Contrôle de la mise en forme des paramètres et des valeurs de retour

En ce qui concerne la propriété use, qui contrôle la mise en forme des paramètres de méthode de service Web ou une valeur de retour, le choix par défaut dans un service Web ASP.NET de style de document est littéral. Le choix par défaut dans un service Web ASP.NET de style RPC est encodé. Vous pouvez modifier la valeur use en définissant la propriété Use des attributs SoapDocumentMethodAttribute, SoapDocumentServiceAttribute, SoapRpcMethodAttribute ou SoapRpcServiceAttribute correspondants sur SoapBindingUse.Literal ou SoapBindingUse.Encoded.

Pour plus d'informations sur le sujet suivant la définition de la propriété Use, consultez Comment : contrôler la mise en forme des paramètres et des valeurs de retour pour une méthode de service Web.

Contrôler si les paramètres sont joints dans un élément XML supplémentaire

Les paramètres ou la valeur de retour pour une méthode de service Web peuvent être encapsulés automatiquement dans un élément XML parent dans l'élément Body du message SOAP. Le développeur n'a pas à spécifier l'élément parent. Comme vous l'avez vu, le style de mise en forme RPC s'en charge. Toutefois, c'est également possible avec un style de mise en forme document. Au lieu que l'élément XML parent ou le wrapper soit spécifié dans le document WSDL, l'élément supplémentaire est inséré implicitement par l'infrastructure de services Web lors de l'exécution.

Cette convention est appelée encapsulation et peut être spécifiée en affectant à la propriété SoapDocumentMethod.ParameterStyle ou SoapDocumentService.ParameterStyle la valeur SoapParameterStyle.Wrapped. Wrapped est également la valeur par défaut.

L'énumération SoapParameterStyle a également la valeur Default pour spécifier le style de paramètre par défaut au niveau de la classe service, ainsi que la valeur Bare pour désactiver l'encapsulation et traduire littéralement les éléments XML spécifiés par le WSDL comme parties de message en paramètres de méthode et valeurs de retour. Avec un style de paramètre Bare, chaque paramètre ou valeur de retour correspond à une partie de message spécifiée.

Le choix d'encapsuler ou non n'est pas spécifié dans un document WSDL ; avec à la fois Wrapped et Bare, le style de liaison utilisé est document. Le choix implique plutôt la liaison entre XML et code – entre le XML défini dans le WSDL et les paramètres et valeurs de retour des méthodes.

Si la propriété ParameterStyle a la valeur SoapParameterStyle.Bare, le développeur est en mesure de spécifier un message ayant plusieurs parties – littéralement plusieurs éléments XML qui apparaissent comme enfants de l'élément SOAP Body. Techniquement, plusieurs éléments ne constituent pas un document XML dans la mesure où un document doit avoir une racine unique. Par conséquent, la méthode recommandée dans la communauté de services Web est d'utiliser une partie de message unique avec des services de style document. Chaque méthode de service Web ne doit pas utiliser sa signature prévue, mais une signature où un objet qui mappe à un document XML est le paramètre unique et où un autre objet qui mappe à un document XML est la valeur de retour. Un développeur est tenu d'écrire du code pour extraire ou encapsuler les paramètres true ou les valeurs de retour.

Par conséquent, il suffit normalement à un développeur d'affecter à la propriété ParameterStyle la valeur SoapParameterStyle.Wrapped et de laisser l'infrastructure des services Web s'occuper de placer les paramètres et les valeurs de retour dans les documents XML.

Pour plus d'informations sur le sujet suivant la définition de la propriété ParameterStyle, consultez Comment : contrôler si les paramètres de méthode de service Web sont joints dans un élément supplémentaire.

Définition de la mise en forme SOAP par défaut pour un service Web entier

Comme indiqué précédemment dans cette rubrique, les attributs SoapDocumentServiceAttribute et SoapRpcServiceAttribute peuvent être utilisés pour définir des valeurs par défaut pour le style de mappage style, use et parameter-to-document pour une classe de service Web entière, mais pas pour une classe proxy de client. Les attributs SoapDocumentMethod et SoapRpcMethod peuvent être utilisés pour remplacer des paramètres de niveau service sur la base d'une méthode de service Web.

Pour plus d'informations sur le sujet suivant l'utilisation des attributs SoapDocumentService et SoapRpcService, consultez Comment : modifier le format SOAP par défaut pour l'intégralité d'un service Web.

Personnalisation des messages SOAP avec la sérialisation XML

En plus de spécifier les propriétés style et use et prévoir l'insertion d'un élément wrapper, vous pouvez personnaliser directement le XML dans un message SOAP grâce à la sérialisation XML. Par défaut, l'infrastructure de services Web du .NET Framework sérialise automatiquement les champs publics et les propriétés dans les messages XML.

L'espace de noms System.Xml.Serialization inclut de nombreux attributs pour la manipulation de XML. L'exemple de code suivant montre comment certains de ces attributs peuvent s'appliquer directement aux paramètres de méthode de service Web ou aux valeurs de retour.

[SoapDocumentMethod(
     "https://www.contoso.com/DocumentBareLiteral",
     Use=SoapBindingUse.Literal,
     ParameterStyle=SoapParameterStyle.Bare)]
[return: XmlElement(Namespace="https://www.contoso.com",
                    IsNullable=true)]
public string DocumentBareLiteral(
   [XmlElement(Namespace="https://www.contoso.com",
                     IsNullable=true)] 
   Address1 MyAddress, 
   [XmlElement(Namespace="https://www.contoso.com",
            IsNullable=false)] 
   bool useZipPlus4) {

<SoapDocumentMethod( _
     https://www.contoso.com/DocumentBareLiteral", _
     Use:=SoapBindingUse.Literal, _
     ParameterStyle:= SoapParameterStyle.Bare)> _
Public Function DocumentBareLiteral( _
   ByVal <XmlElement([Namespace]:="https://www.contoso.com", _
                      IsNullable:=true)> _
   MyAddress As Address1, _
   ByVal <XmlElement([Namespace]:="https://www.contoso.com", _
                      IsNullable:=false)> _
   useZipPlus4 As Boolean) _
   As <XmlElement([Namespace]:="https://www.contoso.com", _
                  IsNullable:=true)> _
   String

Certains attributs communément utilisés sont répertoriés comme suit ; leur nom apparaît sans le suffixe Attribute, qui peut être omis :

XmlElement : spécifie qu'un champ public ou une propriété publique doit être sérialisée comme élément XML. C'est l'attribut par défaut pour sérialiser des champs publics non-tableau et des propriétés. Lorsque l'attribut XmlElement est appliqué aux champs publics et aux propriétés publiques d'un attribut de type tableau, le tableau est sérialisé avec les autres membres, sans élément parent spécial.
XmlAttribute : spécifie qu'un champ public ou une propriété publique doit être sérialisé comme attribut XML de l'élément qui représente le type conteneur.
XmlArray : spécifie qu'un champ public de type tableau doit être sérialisé avec un élément parent spécial. C'est l'attribut par défaut pour sérialiser des champs publics et des propriétés publiques de type tableau.
XmlArrayItem : utilisé en association avec l'attribut XmlArray pour contrôler les éléments de tableau.
XmlIgnore : spécifie qu'un champ public ou une propriété publique ne doit pas être sérialisé.

Les attributs précédents, à l'exception de XmlIgnore, peuvent également être utilisés pour spécifier un élément ou un nom d'attribut en plus de la valeur par défaut, qui est le nom de membre pour les membres non-tableau. Ils peuvent également être utilisés pour spécifier un espace de noms pour un élément particulier. D'habitude, un service Web ne mélange pas les espaces de noms et il suffit qu'un espace de noms soit spécifié au niveau de la classe, à l'aide d'un attribut tel que WebService ou WebServiceBinding.

Pour plus d'informations, consultez , consultez System.Xml.Serialization.

Remarque :
Pour le RPC ou les services Web encodés utilisant le style RPC avec l'encodage SOAP, l'utilisation de la sérialisation XML est restreinte. Les paramètres et valeurs de retour apparaissent automatiquement sans qualification d'espace de noms. De même, l'encodage selon SOAP 1.1 Section 5, combiné au style document ou RPC, interdit la liaison de données aux attributs XML.

Remarque :
Si une classe de service abstraite ou un classe proxy de client est générée à partir d'un document WSDL, les attributs System.Xml.Serialization corrects sont appliqués automatiquement pour les éléments de schéma XML et types définis sous l'élément types WSDL (quelles que soient les conditions : en ligne ou après importation).

Remarque :
L'utilisation de types Nullable dans un service Web génère du WSDL contenant le paramètre « nillable=true » pour le type. Toutefois, lorsque des types Nullable sont utilisés directement comme paramètres de méthode Web ou valeurs de retour, l'acceptation de la valeur Null ne se sera pas répercutée dans le WSDL généré dans les cas suivants: 1) si des messages SOAP basés sur RPC sont utilisés, et 2) si des messages SOAP basés sur le document sont utilisés avec des paramètres encodés en mode Bare.

L'utilisation de types Nullable dans un service Web génère du WSDL contenant le paramètre « nillable=true » pour le type. Toutefois, lorsque des types Nullable sont utilisés directement comme paramètres de méthode Web ou valeurs de retour, l'acceptation de la valeur Null ne se sera pas répercutée dans le WSDL généré dans les cas suivants: 1) si des messages SOAP basés sur RPC sont utilisés, et 2) si des messages SOAP basés sur le document sont utilisés avec des paramètres encodés en mode Bare.

Pour plus d'informations sur le sujet suivant l'utilisation de l'attribut XmlElement, consultez Comment : personnaliser des messages SOAP avec la sérialisation XML.

Voir aussi

Prise en charge du .NET Framework pour les formats SOAP

Contrôle de la mise en forme globale du corps SOAP

Contrôle de la mise en forme des paramètres et des valeurs de retour

Contrôler si les paramètres sont joints dans un élément XML supplémentaire

Définition de la mise en forme SOAP par défaut pour un service Web entier

Personnalisation des messages SOAP avec la sérialisation XML

Voir aussi

Tâches

Référence

Concepts

Autres ressources

Ressources supplémentaires