Partager via

Personnalisation des messages SOAP

  • Article

Pour les services Web XML créés à l'aide d'ASP.NET et leurs clients utilisant SOAP pour communiquer avec les méthodes de service Web XML, un mécanisme sophistiqué est disponible pour contrôler la mise en forme du message SOAP envoyé au serveur et attendu en retour. SOAP impose que le contenu du message SOAP envoyé à destination et en provenance du service Web XML soit au format XML. La mise en forme du XML n'est cependant pas strictement décrite. Pour travailler avec les services Web XML qui prévoient une mise en forme différente, ASP.NET fournit un mécanisme à base d'attributs pour contrôler le format du XML dans le message SOAP. De plus, un mécanisme à base d'attributs pour spécifier les noms d'attribut et d'élément spécifiques du SOAP transmis sur le réseau est disponible pour contrôler le SOAP de manière plus précise.

La communication entre les services Web XML et leurs clients est imposée en grande partie par deux normes industrielles : SOAP et le langage WSDL (Web Services Description Language). SOAP définit un schéma de mise en forme pour les données qui apparaissent sous l'élément Body et un schéma de mise en forme des paramètres dans cet élément. La première est appelée SOAP section 7 ou simplement RPC. Pour plus d'informations sur la spécification SOAP, consultez le site Web du W3C (http://www.w3.org/TR/SOAP). La deuxième est appelée SOAP section 5 ou simplement Encoded. WSDL, utilisé pour décrire les messages SOAP attendus par un service Web XML, permet aux services de déclarer qu'ils acceptent les messages RPC avec des paramètres codés mais définit par ailleurs deux autres termes : Literal et Document. Literal, comme Encoded, se réfère à la façon dont les paramètres sont mis en forme. Document, comme RPC, se réfère à la façon dont l'élément Body global est mis en forme.

Personnalisation du SOAP envoyé par un client de service Web XML

Le tableau suivant décrit les styles de mise en forme pris en charge par les services Web XML créés à l'aide d'ASP.NET et les attributs qui accomplissent chaque combinaison spécifique. Les attributs ayant un suffixe Service peuvent être appliqués à une classe implémentant un service Web XML pour définir le style de mise en forme par défaut des méthodes de service Web XML dans la classe. Les attributs ayant un suffixe Method ne peuvent être appliqués qu'à une méthode de service Web XML ou à une méthode dans une classe proxy appelant une méthode de service Web XML. Les détails de chaque combinaison sont abordés dans les paragraphes suivants.

    Mise en forme globale du corps SOAP
Mise en forme du paramètre Messages SOAP Document Messages SOAP RPC conformément à SOAP Section 7
Literal — basé sur un schéma XSD pour chaque paramètre SoapDocumentMethod ou SoapDocumentService

Use=Literal

Il s'agit de l'option par défaut.

 Non pris en charge.
Encoded - Règles de codage SOAP Section 5 SoapDocumentMethod ou SoapDocumentService

Use=Encoded

SoapRpcMethod ou SoapRpcService

Modification de la mise en forme des paramètres

L'une des premières décisions à prendre lorsque vous concevez un service Web XML concerne le codage du XML dans la demande SOAP. Souhaitez-vous en effet que le document XML respecte strictement un schéma XSD ou les règles de mise en forme décrites dans la spécification SOAP, sections 5 et 7 ? Les règles de mise en forme de la spécification SOAP, sections 5 et 7, autorisent quelques variations. Ainsi, un destinataire d'une demande SOAP utilisant les règles de codage SOAP doit gérer toutes les variations possibles. Ce qui doit être exactement transmis dans une demande SOAP peut être concrètement défini, en définissant un schéma XSD pour la méthode de service Web XML. Par défaut, les services Web XML créés à l'aide d'ASP.NET doivent utiliser le passage de documents basé sur les schémas.

Puisque les paramètres pour une méthode de service Web XML peuvent constituer la majorité des données passées dans une demande ou une réponse SOAP, leur mappage à des éléments XML détermine l'apparence du document XML. Le langage WSDL (Web Services Description Language) définit deux styles de mise en forme pour les paramètres : Encoded et Literal. Encoded fait référence à la mise en forme des paramètres à l'aide du codage SOAP décrit dans la spécification de la section 5. Literal fait référence au mappage des paramètres utilisant un schéma XSD prédéfini pour chaque paramètre.

Avec un client de service Web XML, vous pouvez choisir la façon dont les paramètres sont mappés à des éléments XML pour que cela corresponde à ce que le service Web XML attend. Les services Web XML prennent en charge les styles de mise en forme des paramètres Literal et Encoded. Cette prise en charge varie en fonction du choix de mise en forme de la méthode de service Web XML. Pour plus d'informations, consultez Modification de la mise en forme globale du corps SOAP.

Notez que bien qu'ASP.NET fournisse une architecture complète pour contrôler la mise en forme du XML, l'ordre dans lequel les paramètres sont sérialisés n'est pas garanti.

Pour spécifier la mise en forme du paramètre Literal

  • Appliquez un attribut SoapDocumentMethod à une méthode de la classe proxy, en affectant SoapBindingUse.Literal à la propriété Use.

    L'énumération SoapBindingUse spécifie les styles de mise en forme des paramètres disponibles pour un service Web XML créé à l'aide d'ASP.NET.

    [SoapDocumentMethod(
    "https://www.contoso.com/DocumentLiteral",
    RequestNamespace="https://www.contoso.com",
    ResponseNamespace="https://www.contoso.com",
    Use=SoapBindingUse.Literal)]
public string DocumentLiteral(Address1 address, bool useZipPlus4) {
[Visual Basic]
<SoapDocumentMethod( _
   "https://www.contoso.com/DocumentLiteral", _
   RequestNamespace:="https://www.contoso.com", _
   ResponseNamespace:="https://www.contoso.com", _
   Use:=SoapBindingUse.Literal)>  _
Public Function DocumentLiteral(ByVal address As Address1, _
                         ByVal useZipPlus4 As Boolean) As String

    La partie XML de la demande SOAP à la méthode de service Web XML DocumentLiteral suit. Les paramètres résident dans l'élément Body et sont codés comme des documents XML autonomes puisqu'ils se réfèrent à un schéma XSD.

    <?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <DocumentLiteral xmlns="https://www.contoso.com">
      <address>
        <Street>One Microsoft Way</Street>
        <City>Redmond</City>
        <Zip>98052</Zip>
      </address>
      <useZipPlus4>True</useZipPlus4>
    </DocumentLiteral>
  </soap:Body>
</soap:Envelope>

Pour spécifier une mise en forme du paramètre Encoded

  • Appliquez un attribut SoapDocumentMethod ou SoapRpcMethod à la méthode de la classe proxy, en affectant SoapBindingUse. Encoded à la propriété Use.

    Contrairement au style de mise en forme du paramètre Literal, celui du paramètre Encoded peut être utilisé conjointement aux deux styles de mise en forme de la méthode de service Web XML. Pour plus d'informations sur les styles de mise en forme de la méthode de service Web XML, consultez Modification de la mise en forme globale du corps SOAP

    [SoapDocumentMethod("https://www.contoso.com/DocumentEncoded",
                    RequestNamespace="https://www.contoso.com",
                    ResponseNamespace="https://www.contoso.com",
                    Use=SoapBindingUse.Encoded)]
public string DocumentEncoded(Address address, bool useZipPlus4) {
[Visual Basic]
<SoapDocumentMethod("https://www.contoso.com/DocumentEncoded", _
                    RequestNamespace:="https://www.contoso.com", _
                    ResponseNamespace:="https://www.contoso.com", _
                    Use:=SoapBindingUse.Encoded)>  _
Public Function DocumentEncoded(ByVal address As Address, _ 
                  ByVal useZipPlus4 As Boolean) As String

    La partie XML de la demande SOAP à la méthode de service DocumentEncoded suit. Notez la représentation très différente des paramètres par rapport au style de mise en forme Literal ; ils sont en effet mis en forme à l'aide des règles de codage décrites dans la Section 5 de la spécification SOAP. Faites particulièrement attention au paramètre address qui n'est pas un type de données simple.

    <?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soapenc="https://schemas.xmlsoap.org/soap/encoding/"
xmlns:tns="https://www.contoso.com"
xmlns:tnsTypes="https://www.contoso.com/encodedTypes"
xmlns:wsdl="https://schemas.xmlsoap.org/wsdl/"
xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body soap:encodingStyle="https://schemas.xmlsoap.org/soap/encoding/">
    <tnsTypes:DocumentEncoded>
      <address href="#1" />
      <useZipPlus4>boolean</useZipPlus4>
    </tnsTypes:DocumentEncoded>
    <tnsTypes:Address id="1">
      <Street id="2">string</Street>
      <City id="3">string</City>
      <Zip id="4">string</Zip>
    </tnsTypes:Address>
  </soap:Body>
</soap:Envelope>

Modification de la mise en forme globale du corps SOAP

WSDL définit deux styles de mise en forme d'une méthode de service Web XML (qu'il appelle opération) dans l'élément Body d'une demande ou d'une réponse SOAP : RPC et Document. Dans ASP.NET, les deux styles de mise en forme Document et RPC sont pris en charge. Document est la valeur par défaut.

Le style RPC se réfère à la mise en forme de l'élément Body selon la section 7 de la spécification SOAP. Ce style spécifie que tous les paramètres sont encapsulés dans un seul élément, nommé d'après la méthode de service Web XML, et que chaque élément dans cet élément représente un paramètre nommé d'après son nom de paramètre respectif. Il décrit aussi les règles de mise en forme des réponses SOAP.

Le style Document se réfère à la mise en forme de l'élément Body comme une série d'une ou plusieurs parties du message sous l'élément Body. La forme exacte de chaque partie du message est déterminée par les propriétés Use et ParameterStyle de l'attribut SoapDocumentMethod. La propriété Use détermine si les paramètres sont mis en forme comme Encoded ou Literal. ParameterStyle détermine si les paramètres sont encapsulés dans une partie unique du message sous l'élément Body ou si chaque paramètre est une partie du message. Pour plus d'informations sur la définition de la propriété ParameterStyle, consultez Modification de l'encapsulation éventuelle des paramètres dans un seul élément XML.

Pour spécifier un style de mise en forme Document

  • Appliquez un attribut SoapDocumentMethod à la méthode de la classe proxy appelant la méthode de service Web XML pertinente.

    Avec le style de mise en forme Document, les services Web XML créés à l'aide d'ASP.NET prennent en charge l'utilisation des deux styles de mise en forme des paramètres Literal et Encoded. L'exemple suivant combine le style de mise en forme du paramètre Document et celui du paramètre Literal.

    [SoapDocumentMethod("https://www.contoso.com/DocumentWrappedLiteral",
                    RequestNamespace="https://www.contoso.com",
                    ResponseNamespace="https://www.contoso.com",
                    Use=SoapBindingUse.Literal)]
public string DocumentWrappedLiteral(Address MyAddress, 
                                     bool useZipPlus4) {
[Visual Basic]
<SoapDocumentMethod("https://www.contoso.com/DocumentWrappedLiteral", _
                    RequestNamespace:="https://www.contoso.com", _
                    ResponseNamespace:="https://www.contoso.com", _
                    Use:=SoapBindingUse.Literal)> _
   Public Function DocumentWrappedLiteral(ByVal MyAddress As Address, _
                             ByVal useZipPlus4 As Boolean)As String

    Comme prévu avec le style de mise en forme Document, un schéma XSD est défini dans la description de service qui définit la demande et la réponse SOAP. Ce qui suit est un extrait de la description de service de la demande SOAP pour la méthode de service Web XML DocumentWrappedLiteral. Puisque le premier paramètre de la méthode de service Web XML DocumentWrappedLiteral est une classe et que le style de mise en forme du paramètre Literal a été spécifié, un schéma XSD est créé pour le type address.

    <s:elementname="DocumentWrappedLiteral">
  <s:complexType>
    <s:sequence>
       <s:element minOccurs="1" maxOccurs="1" name="MyAddress"nillable="true" type="s0:Address" /> 
       <s:element minOccurs="1" maxOccurs="1" name="useZipPlus4" type="s:boolean" /> 
    </s:sequence>
  </s:complexType>
</s:element>

<s:complexType name="Address">
   <s:sequence>
      <s:element minOccurs="1" maxOccurs="1" name="Street"nillable="true" type="s:string" /> 
      <s:element minOccurs="1" maxOccurs="1" name="City" nillable="true" type="s:string" /> 
      <s:element minOccurs="1" maxOccurs="1" name="Zip" nillable="true"
                 type="s:string" /> 
   </s:sequence>
</s:complexType>

    Si nous prenons par exemple le schéma XSD défini dans la description de service, la partie XML de la demande SOAP à la méthode de service DocumentWrappedLiteral suit. Notez que les éléments XML sous l'élément Body de la demande SOAP correspondent aux éléments définis dans le schéma XSD.

    <?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xmlns:xsd="http://www.w3.org/2001/XMLSchema"
               xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <DocumentWrappedLiteral xmlns="https://www.contoso.com">
      <MyAddress>
        <Street>string</Street>
        <City>string</City>
        <Zip>string</Zip>
      </MyAddress>
      <useZipPlus4>boolean</useZipPlus4>
    </DocumentWrappedLiteral>
  </soap:Body>
</soap:Envelope>

Pour spécifier le style de mise en forme RPC

  • Appliquez un attribut SoapRpcMethod à la méthode de la classe proxy appelant la méthode de service Web XML pertinente.

    Avec le style de mise en forme RPC, ASP.NET prend juste en charge le style de mise en forme du paramètre Encoded. Par conséquent, l'exemple de code suivant ne spécifie pas de propriété Use pour la mise en forme de paramètre car l'attribut SoapRpcMethod n'a pas de propriété Use.

    [SoapRpcMethodAttribute("https://www.contoso.com/Rpc",
                        RequestNamespace="https://www.contoso.com",
                        ResponseNamespace="https://www.contoso.com")]
public Address Rpc(Address address, bool useZipPlus4) {
[Visual Basic]
<SoapRpcMethodAttribute("https://www.contoso.com/Rpc", _
                        RequestNamespace:="https://www.contoso.com", _
                        ResponseNamespace:="https://www.contoso.com")> _
Public Function Rpc(ByVal address As Address, _
                    ByVal useZipPlus4 As Boolean) As Address

    Un schéma XSD n'est pas strictement défini dans la description de service pour la demande ou la réponse SOAP à la méthode Rpc de l'exemple précédent, mais les parties qui le constituent le sont. Examinez par conséquent la demande SOAP pour la méthode Rpc, en notant que les paramètres sont encapsulés dans un seul élément et codés à l'aide de la mise en forme du paramètre Encoded.

    <?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:xsd="http://www.w3.org/2001/XMLSchema"
             xmlns:soapenc="https://schemas.xmlsoap.org/soap/encoding/"
             xmlns:tns="https://www.contoso.com"
             xmlns:tnsTypes="https://www.contoso.com/encodedTypes"
             xmlns:wsdl="https://schemas.xmlsoap.org/wsdl/"
             xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body soap:encodingStyle="https://schemas.xmlsoap.org/soap/encoding/">
    <tns:Rpc>
      <address href="#1" />
      <useZipPlus4>boolean</useZipPlus4>
    </tns:Rpc>
    <tnsTypes:Address id="1">
      <Street id="2">string</Street>
      <City id="3">string</City>
      <Zip id="4">string</Zip>
    </tnsTypes:Address>
  </soap:Body>
</soap:Envelope>

Modification de l'encapsulation éventuelle des paramètres dans un seul élément XML

Les paramètres pour une méthode de service Web XML peuvent être encapsulés dans un seul élément XML lorsqu'ils sont mappés à des éléments XML résidant dans l'élément Body du message SOAP. Comme vous l'avez vu, RPC encapsule toujours les paramètres dans un seul élément ; vous avez cependant le choix lors de l'utilisation du style de mise en forme Document. Dans la description de service, les paramètres sont mappés à des « portions » du message SOAP, appelés parties du message. Lorsque les paramètres sont encapsulés dans un seul élément XML, ils sont mappés à une partie unique du message. Inversement, s'ils ne le sont pas, ils peuvent être constitués de plusieurs parties.

Pour spécifier que les paramètres sont encapsulés dans un seul élément XML

  • Appliquez un attribut SoapDocumentMethod à la méthode de la classe proxy appelant la méthode de service Web XML pertinente, en affectant Wrapped à la propriété ParameterStyle.

    L'exemple de code suivant affecte Wrapped à ParameterStyle. Il affecte aussi Literal au style de mise en forme du paramètre.

    [SoapDocumentMethod("https://www.contoso.com/DocumentWrappedLiteral",
                    RequestNamespace="https://www.contoso.com",
                    ResponseNamespace="https://www.contoso.com", 
                    Use=SoapBindingUse.Literal, 
                    ParameterStyle=SoapParameterStyle.Wrapped)]
public string DocumentWrappedLiteral(Address1 address, 
                                     bool useZipPlus4) {
[Visual Basic]
<SoapDocumentMethod("https://www.contoso.com/DocumentWrappedLiteral", _
                    RequestNamespace:="https://www.contoso.com", _
                    ResponseNamespace:="https://www.contoso.com", _
                    Use:=SoapBindingUse.Literal, _
                    ParameterStyle:=SoapParameterStyle.Wrapped)> _
Public Function DocumentWrappedLiteral(ByVal address As Address1, _
                             ByVal useZipPlus4 As Boolean) As String

    La partie XML de la demande SOAP encapsule les paramètres dans un élément nommé par défaut d'après la méthode de service Web XML.

    <?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xmlns:xsd="http://www.w3.org/2001/XMLSchema"
               xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <DocumentWrappedLiteral xmlns="https://www.contoso.com">
      <MyAddress>
        <Street>string</Street>
        <City>string</City>
        <Zip>string</Zip>
      </MyAddress>
      <useZipPlus4>boolean</useZipPlus4>
    </DocumentWrappedLiteral>
  </soap:Body>
</soap:Envelope>

    La partie XML de la réponse SOAP encapsule les paramètres out pour la méthode de service Web XML, y compris le résultat dans un élément. Le nom de l'élément d'encapsulation, par défaut, est le nom de la méthode de service Web XML, Response y étant ajouté.

    <?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xmlns:xsd="http://www.w3.org/2001/XMLSchema"
               xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <DocumentWrappedLiteralResponse xmlns="https://www.contoso.com">
      <DocumentWrappedLiteralResult>string
      </DocumentWrappedLiteralResult>
    </DocumentWrappedLiteralResponse>
  </soap:Body>
</soap:Envelope>

Pour spécifier que les paramètres suivent directement l'élément Body

  • Appliquez un attribut SoapDocumentMethod à la méthode de la classe proxy appelant la méthode de service Web XML pertinente, en affectant Bare à la propriété ParameterStyle.

    L'exemple suivant, généré par Wsdl.exe, affecte Bare à ParameterStyle ainsi que Literal au style de mise en forme du paramètre. Puisque l'espace de noms ne peut pas être spécifié dans un élément encapsulant tous les paramètres, il doit être spécifié individuellement pour chaque paramètre et valeur de retour. L'application de XmlElementAttribute à chaque paramètre et à la valeur de retour, ainsi que la définition de la propriété Namespace, peut y parvenir.

    [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) {
[Visual Basic]
<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

    Les éléments XML auxquels les paramètres sont mappés dans la demande SOAP suivent directement l'élément Body, chacun spécifiant un espace de noms.

    <?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xmlns:xsd="http://www.w3.org/2001/XMLSchema"
               xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <MyAddress xmlns="https://www.contoso.com">
      <Street>string</Street>
      <City>string</City>
      <Zip>string</Zip>
    </MyAddress>
    <useZipPlus4 xmlns="https://www.contoso.com">boolean</useZipPlus4>
  </soap:Body>
</soap:Envelope>

    Les paramètres out, y compris la valeur de retour, sont mappés aux éléments XML suivant l'élément Body dans la réponse SOAP. Le nom de l'élément de valeur de retour est le nom de la méthode de service Web XML avec un suffixe Result par défaut.

    <?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <DocumentBareLiteralResult xmlns="https://www.contoso.com">
       string</DocumentBareLiteralResult>
  </soap:Body>
</soap:Envelope>

Personnalisation du SOAP attendu par une méthode de service Web XML

Si vous devez modifier le SOAP attendu par un service Web XML créé à l'aide de ASP.NET, vous pouvez faire appel aux mêmes mécanismes que ceux utilisés pour un client de service Web XML créé à l'aide de ASP.NET. Vous pouvez contrôler le mappage des paramètres à des éléments XML (l'élément XML représentant la méthode de service Web XML) et si les éléments mappés sont encapsulés dans un élément. Les mêmes attributs peuvent être utilisés pour chaque méthode, à savoir SoapDocumentMethod et SoapRpcMethod. De plus, vous pouvez définir les paramètres de mise en forme par défaut au niveau du service Web XML en appliquant les attributs SoapDocumentService et SoapRpcService correspondants au service Web XML. L'application d'un attribut SoapDocumentService à un service Web XML affecte Document au style de mise en forme par défaut de ses méthodes. De même, la valeur par défaut de l'attribut SoapRpcService est RPC.

Pour définir le style de mise en forme de la méthode par défaut pour un service Web XML

  • Appliquez un attribut SoapRpcService ou SoapDocumentService à la classe implémentant le service Web XML.

    L'exemple de code suivant affecte Document au style de mise en forme de la méthode, Literal à la mise en forme du paramètre par défaut et spécifie que les paramètres doivent être encapsulés dans un seul élément.

    <%@ WebService Language="C#" Class="SoapDocumentServiceSample" %>
 using System.Web.Services;
 using System.Web.Services.Protocols;
 using System.Web.Services.Description;

[SoapDocumentService(Use=SoapBindingUse.Literal,
                     ParameterStyle=SoapParameterStyle.Wrapped)]
[WebService(Namespace="https://www.contoso.com")]
public class SoapDocumentServiceSample  
{
    [ WebMethod ]
    public string UseDefaultEncoding(Address MyAddress, 
                                     bool useZipPlus4) 
    {
     return "Use the default encodings for this XML Web service.";
    }
}
[Visual Basic]
<%@ WebService Language="VB" Class="SoapDocumentServiceSample" %>
Imports System.Web.Services
Imports System.Xml.Serialization
Imports System.Web.Services.Protocols
Imports System.Web.Services.Description

< SoapDocumentService(Use := SoapBindingUse.Literal, _
                      ParameterStyle := SoapParameterStyle.Wrapped)> _
Public Class SoapDocumentServiceSample
  < WebMethod > _
  Public Function UseDefaultEncoding(MyAddress as Address, _
                                     useZipPlus4 As Boolean) As String 
     Return "Use the default formattings for this XML Web service."
  End Function
End Class

    La partie XML de la demande SOAP attendue par la méthode de service Web XML UseDefaultEncoding suit.

    <?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xmlns:xsd="http://www.w3.org/2001/XMLSchema"
               xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <UseDefaultEncoding xmlns="https://www.contoso.com">
      <MyAddress>
        <Street>string</Street>
        <City>string</City>
        <Zip>string</Zip>
      </MyAddress>
      <useZipPlus4>boolean</useZipPlus4>
    </UseDefaultEncoding>
  </soap:Body>
</soap:Envelope>

Personnalisation du message SOAP avec la sérialisation XML

En plus de spécifier la mise en forme du paramètre, le style de mise en forme pour la méthode de service Web XML et si les paramètres sont encapsulés dans un seul élément ou non, vous pouvez directement personnaliser un message SOAP grâce à la sérialisation XML. Vous l'avez déjà vu dans une certaine mesure avec l'attribut XmlElement, mais l'espace de noms System.Xml.Serialization comprend de nombreux attributs permettant de manipuler le XML. Supposons que SOAP utilise le XML pour coder les données envoyées au service Web XML et reçues de lui, les attributs de l'espace de noms System.Xml.Serialization sont parfaits pour personnaliser le SOAP à destination et en provenance du service. Pour plus d'informations, consultez System.Xml.Serialization.

Pour spécifier le nom de l'élément XML représentant un paramètre

  • Appliquez un attribut XmlElement au paramètre en spécifiant le nom souhaité de l'élément et éventuellement un espace de noms si Literal est affecté à la mise en forme du paramètre. Si la mise en forme du paramètre a la valeur Encoded, appliquez un attribut SoapElement au paramètre.

    L'exemple de code suivant prévoit que les noms d'élément représentant les paramètres sont MyAddressElement, MyZipElement et ReturnValueElement. Il prévoit aussi que le nom d'élément représentant la valeur de retour soit ReturnValueElement. Dans l'exemple, la mise en forme de la méthode de service Web XML est Document, valeur par défaut pour ASP.NET.

    <%@ WebService Language="C#" Class="SoapDocumentServiceSample" %>
 using System.Web.Services;
 using System.Web.Services.Protocols;
 using System.Xml.Serialization;

[WebService(Namespace="https://www.contoso.com")] 
public class SoapDocumentServiceSample  
{
  [ WebMethod ]
  [ return: XmlElement("ReturnValueElement",IsNullable=false)]
  public Address ValidateAddress(
    [XmlElement("MyAddressElement")] Address MyAddress,
    [XmlElement("MyZipElement")] bool useZipPlus4) 
  {
    useZipPlus4 = true;    
    return new Address();
  }
}
[Visual Basic]
<%@ WebService Language="VB" Class="SoapDocumentServiceSample" %>
 Imports System.Web.Services
 Imports System.Web.Services.Protocols
 Imports System.Xml.Serialization

<WebService(Namespace := "https://www.contoso.com")> _
Public Class SoapDocumentServiceSample
  < WebMethod > _
  Public Function ValidateAddress( _
       <XmlElement("MyAddressElement")> MyAddress As Address, _
       <XmlElement("MyZipElement")> useZipPlus4 As Boolean)  
       As <XmlElement("ReturnValueElement",IsNullable :=false)> _
       Address 
        useZipPlus4 = True 
     Return new Address()
  End Function
End Class

    Le service Web XML attend la demande SOAP suivante. Notez que les noms des éléments correspondent à ce qui est spécifié dans l'attribut XmlElement, contrairement aux noms de paramètre.

    <?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <ValidateAddress xmlns="http://tempuri.org/">
      <MyAddressElement>
        <Street>string</Street>
        <City>string</City>
        <Zip>string</Zip>
      </MyAddressElement>
      <MyZipElement>boolean</MyZipElement>
    </ValidateAddress>
  </soap:Body>
</soap:Envelope>

Voir aussi

Introduction à la sérialisation XML | System.Xml.Serialization, espace de noms | Modification du message SOAP à l'aide des extensions SOAP | SoapDocumentMethodAttribute | SoapRpcMethodAttribute | SoapDocumentServiceAttribute | SoapRpcServiceAttribute | Création de services Web XML à l'aide d'ASP.NET | Création de clients de service Web XML