Sérialisation XML à l'aide des services Web XML

La sérialisation XML est le mécanisme de transport sous-jacent utilisé dans l'architecture des services Web XML effectué par XmlSerializer. Pour contrôler le code XML généré par un service Web XML, vous pouvez appliquer les attributs répertoriés dans les attributs qui contrôlent la sérialisation XML et les attributs qui contrôlent la sérialisation codée en SOAP aux classes, valeurs de retour, paramètres et champs d'un fichier utilisé pour créer un service Web XML (.asmx). Pour plus d'informations sur la création d'un service Web XML, consultez Création de services Web XML à l'aide d'ASP.NET.

Styles codé et littéral

Le code XML généré par un service Web XML peut être mis en forme des deux manières suivantes : soit de manière littérale, soit de manière codée, selon les explications fournies dans Personnalisation des messages SOAP. Il existe donc deux ensembles d'attributs qui contrôlent la sérialisation XML. Les attributs répertoriés dans les attributs qui contrôlent la sérialisation XML sont conçus pour contrôler le code XML de style littéral. Les attributs répertoriés dans les attributs qui contrôlent la sérialisation codée en SOAP contrôlent le style codé. En appliquant ces attributs de manière sélective, vous pouvez personnaliser une application pour qu'elle retourne l'un ou l'autre, ou les deux styles. De plus, ces attributs peuvent être appliqués (selon les cas) pour retourner des valeurs et des paramètres.

Exemple d'emploi des deux styles

Lorsque vous créez un service Web XML, vous pouvez utiliser les deux ensembles d'attributs sur les méthodes. Dans l'exemple suivant, la classe nommée MyService contient deux méthodes de service Web XML, MyLiteralMethod et MyEncodedMethod. Ces deux méthodes exécutent la même fonction : retourner une instance de la classe Order. Dans la classe Order, les attributs XmlTypeAttribute et SoapTypeAttribute sont tous deux appliqués au champ OrderID, et des valeurs différentes ont été attribuées à la propriété ElementName de ces deux attributs.

Pour exécuter l'exemple, collez le code dans un fichier avec une extension .asmx, et placez le fichier dans un répertoire virtuel géré par les services IIS (Internet Information Services). À partir d'un navigateur HTML comme Internet Explorer, tapez le nom de l'ordinateur, du répertoire virtuel et le nom du fichier.

<%@ WebService Language="VB" Class="MyService" %>
Imports System
Imports System.Web.Services
Imports System.Web.Services.Protocols
Imports System.Xml.Serialization
Public Class Order
    ' Both types of attributes can be applied. Depending on which type
    ' the method used, either one will affect the call.
    <SoapElement(ElementName:= "EncodedOrderID"), _
    XmlElement(ElementName:= "LiteralOrderID")> _
    public OrderID As String
End Class

Public Class MyService
    <WebMethod, SoapDocumentMethod> _
    public Function MyLiteralMethod() As Order 
        Dim myOrder As Order = New Order()
        return myOrder
    End Function
    <WebMethod, SoapRpcMethod> _
    public Function MyEncodedMethod() As Order 
        Dim myOrder As Order = New Order()
        return myOrder
    End Function
End Class
[C#]
<%@ WebService Language="C#" Class="MyService" %>
using System;
using System.Web.Services;
using System.Web.Services.Protocols;
using System.Xml.Serialization;
public class Order{
    // Both types of attributes can be applied. Depending on which type
    // the method used, either one will affect the call.
    [SoapElement(ElementName = "EncodedOrderID")]
    [XmlElement(ElementName = "LiteralOrderID")]
    public String OrderID;
}
public class MyService{
    [WebMethod][SoapDocumentMethod]
    public Order MyLiteralMethod(){
        Order myOrder = new Order();
        return myOrder;
    }
    [WebMethod][SoapRpcMethod]
    public Order MyEncodedMethod(){
        Order myOrder = new Order();
        return myOrder;
    }
}

L'exemple suivant appelle MyLiteralMethod. Remarquez que le nom d'élément est remplacé par « LiteralOrderID ».

<?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>
        <MyLiteralMethodResponse xmlns="http://tempuri.org/">
            <MyLiteralMethodResult>
                <LiteralOrderID>string</LiteralOrderID>
            </MyLiteralMethodResult>
        </MyLiteralMethodResponse>
    </soap:Body>
</soap:Envelope>

L'exemple suivant appelle MyEncodedMethod. Remarquez que le nom d'élément est remplacé par « EncodeOrderID ».

<?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="http://tempuri.org/" xmlns:types="http://tempuri.org/encodedTypes" xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body soap:encodingStyle="https://schemas.xmlsoap.org/soap/encoding/">
        <tns:MyEncodedMethodResponse>
            <MyEncodedMethodResult href="#id1" />
        </tns:MyEncodedMethodResponse>
        <types:Order id="id1" xsi:type="types:Order">
            <EncodedOrderID xsi:type="xsd:string">string</EncodedOrderID>
        </types:Order>
    </soap:Body>
</soap:Envelope>

Application des attributs aux valeurs de retour

Vous pouvez également appliquer des attributs aux valeurs de retour pour contrôler l'espace de noms, le nom d'élément et ainsi de suite. L'exemple suivant applique l'attribut XmlElementAttribute à la valeur de retour de la méthode MyLiteralMethod. Cette pratique vous permet de contrôler l'espace de noms et le nom d'élément.

    <WebMethod, SoapDocumentMethod> _
    public Function MyLiteralMethod() As _
    <XmlElement(Namespace:="http://www.cohowinery.com", _
    ElementName:= "BookOrder")> _
    Order 
        Dim myOrder As Order = New Order()
        return myOrder
    End Function
[C#]
    [return: XmlElement(Namespace = "http://www.cohowinery.com",
    ElementName = "BookOrder")]
    [WebMethod][SoapDocumentMethod]
    public Order MyLiteralMethod(){
        Order myOrder = new Order();
        return myOrder;
    }

Lorsqu'il est appelé, le code retourne un code XML qui ressemble à ce qui 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>
        <MyLiteralMethodResponse xmlns="http://tempuri.org/">
            <BookOrder xmlns="http://www.cohowinery.com">
                <LiteralOrderID>string</LiteralOrderID>
            </BookOrder>
        </MyLiteralMethodResponse>
    </soap:Body>
</soap:Envelope>

Attributs appliqués aux paramètres

Vous pouvez également appliquer des attributs aux paramètres pour spécifier l'espace de noms, le nom d'élément et ainsi de suite. L'exemple suivant ajoute un paramètre à la méthode MyLiteralMethodResponse et applique l'attribut XmlAttributeAttribute au paramètre. Le nom d'élément et d'espace de noms sont tous deux définis pour le paramètre.

    <WebMethod, SoapDocumentMethod> _
    public Function MyLiteralMethod(<XmlElement _
    ("MyOrderID", Namespace:="https://www.microsoft.com")>ID As String) As _
    <XmlElement(Namespace:="http://www.cohowinery.com", _
    ElementName:= "BookOrder")> _
    Order 
        Dim myOrder As Order = New Order()
        myOrder.OrderID = ID
        return myOrder
    End Function
[C#]
    [return: XmlElement(Namespace = "http://www.cohowinery.com",
    ElementName = "BookOrder")]
    [WebMethod][SoapDocumentMethod]
    public Order MyLiteralMethod([XmlElement("MyOrderID", 
    Namespace="https://www.microsoft.com")] string ID){
        Order myOrder = new Order();
        myOrder.OrderID = ID;
        return myOrder;
    } 

La demande SOAP ressemble à ce qui 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>
        <MyLiteralMethod xmlns="http://tempuri.org/">
            <MyOrderID xmlns="https://www.microsoft.com">string</MyOrderID>
        </MyLiteralMethod>
    </soap:Body>
</soap:Envelope>

Application des attributs aux classes

Si vous avez besoin de contrôler l'espace de noms des éléments qui correspondent aux classes, vous pouvez appliquer XmlTypeAttribute, XmlRootAttribute, et SoapTypeAttribute selon vos besoins. L'exemple suivant applique ces trois attributs à la classe Order.

<XmlType("BigBookService"), _
SoapType("SoapBookService"), _
XmlRoot("BookOrderForm")> _
Public Class Order
    ' Both types of attributes can be applied. Depending on which
    ' the method used, either one will affect the call.
    <SoapElement(ElementName:= "EncodedOrderID"), _
    XmlElement(ElementName:= "LiteralOrderID")> _
    public OrderID As String
End Class
[C#]
[XmlType("BigBooksService", Namespace = "http://www.cpandl.com")]
[SoapType("SoapBookService")]
[XmlRoot("BookOrderForm")]
public class Order{
    // Both types of attributes can be applied. Depending on which
    // the method used, either one will affect the call.
    [SoapElement(ElementName = "EncodedOrderID")]
    [XmlElement(ElementName = "LiteralOrderID")]
    public String OrderID;
}

Les résultats de l'application de XmlTypeAttribute et SoapTypeAttribute se voient à l'examen de la description de service, comme le montre l'exemple suivant.

    <s:element name="BookOrderForm" type="s0:BigBookService" /> 
- <s:complexType name="BigBookService">
- <s:sequence>
    <s:element minOccurs="0" maxOccurs="1" name="LiteralOrderID" type="s:string" /> 
    </s:sequence>

- <s:schema targetNamespace="http://tempuri.org/encodedTypes">
- <s:complexType name="SoapBookService">
- <s:sequence>
    <s:element minOccurs="1" maxOccurs="1" name="EncodedOrderID" type="s:string" /> 
    </s:sequence>
    </s:complexType>
    </s:schema>

L'effet de XmlRootAttribute est également visible dans les résultats HTTP GET et HTTP POST, comme illustré ci-dessous.

<?xml version="1.0" encoding="utf-8"?>
<BookOrderForm xmlns="http://tempuri.org/">
    <LiteralOrderID>string</LiteralOrderID>
</BookOrderForm>

Voir aussi

Sérialisation XML | Attributs qui contrôlent la sérialisation codée en SOAP | Génération de messages SOAP à l'aide de la sérialisation XML | Introduction à la sérialisation XML