以 XML Web 服務進行 XML 序列化XML Serialization with XML Web Services

XML 序列化為 XML Web 服務架構中使用的基礎傳輸機制,由 XmlSerializer 類別執行。XML serialization is the underlying transport mechanism used in the XML Web services architecture, performed by the XmlSerializer class. 若要控制 XML Web Service 產生的 XML,可將列在控制 XML 序列化的屬性控制編碼 SOAP 序列化的屬性中的屬性,套用至用來建立 XML Web Service (.asmx) 之檔案的類別、傳回值、參數以及欄位。To control the XML generated by an XML Web service, you can apply the attributes listed in both Attributes That Control XML Serialization and Attributes That Control Encoded SOAP Serialization to the classes, return values, parameters, and fields of a file used to create an XML Web service (.asmx). 如需建立 XML Web service 的詳細資訊,請參閱 < ASP.NET XML Web Service 使用For more information about creating an XML Web service, see XML Web Services Using ASP.NET.

常值與編碼樣式Literal and Encoded Styles

XML Web service 所產生的 XML 可以是其中一種方式,常值格式或編碼中所述自訂 SOAP 訊息格式The XML generated by an XML Web service can be formatted in either one of two ways, either literal or encoded, as explained in Customizing SOAP Message Formatting. 因此有兩組屬性控制 XML 序列化。Therefore there are two sets of attributes that control XML serialization. 列在控制 XML 序列化的屬性中的屬性設計用來控制常值樣式 XML。The attributes listed in Attributes That Control XML Serialization are designed to control literal style XML. 列在控制編碼 SOAP 序列化的屬性中的屬性則可控制編碼樣式。The attributes listed in Attributes That Control Encoded SOAP Serialization control the encoded style. 您可選擇性地套用這些屬性,自訂應用程式傳回其中一種或同時兩種樣式。By selectively applying these attributes, you can tailor an application to return either, or both styles. 除此之外,可將這些屬性套用至傳回值和參數 (如果適合的話)。Furthermore, these attributes can be applied (as appropriate) to return values and parameters.

同時使用兩種樣式的範例Example of Using Both Styles

當您建立 XML Web 服務,可同時使用方法上的兩組屬性。When you're creating an XML Web service, you can use both sets of attributes on the methods. 在下列程式碼範例中,名為 MyService``MyLiteralMethod的類別包含兩個 XML Web 服務方法:MyEncodedMethod 及 。In the following code example, the class named MyService contains two XML Web service methods, MyLiteralMethod and MyEncodedMethod. 兩種方法都執行相同功能:傳回 Order 類別的執行個體。Both methods perform the same function: returning an instance of the Order class. Order 類別中,XmlTypeAttribute 以及 SoapTypeAttribute 屬性 (attribute) 都套用至 OrderID 欄位,而且兩個屬性 (attribute) 的 ElementName 屬性 (property) 都設為不同值。In the Order class, the XmlTypeAttribute and the SoapTypeAttribute attributes are both applied to the OrderID field, and both attributes have their ElementName property set to different values.

若要執行這個範例,請將程式碼貼至副檔名為 .asmx 的檔案中,並將該檔置於 Internet Information Services (IIS) 管理的虛擬目錄中。To run the example, paste the code into a file with an .asmx extension, and place the file into a virtual directory managed by Internet Information Services (IIS). 從 Internet Explorer 這類 HTML 瀏覽器中,輸入電腦、虛擬目錄及檔案的名稱。From an HTML browser, such as Internet Explorer, type the name of the computer, virtual directory, and file.

<%@ 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  
<%@ 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;  
    }  
}  

下列程式碼範例呼叫 MyLiteralMethodThe following code example calls MyLiteralMethod. 項目名稱變更為 "LiteralOrderID"。The element name is changed to "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="http://schemas.xmlsoap.org/soap/envelope/">  
    <soap:Body>  
        <MyLiteralMethodResponse xmlns="http://tempuri.org/">  
            <MyLiteralMethodResult>  
                <LiteralOrderID>string</LiteralOrderID>  
            </MyLiteralMethodResult>  
        </MyLiteralMethodResponse>  
    </soap:Body>  
</soap:Envelope>  

下列程式碼範例呼叫 MyEncodedMethodThe following code example calls MyEncodedMethod. 項目名稱為 "EncodedOrderID"。The element name is "EncodedOrderID".

<?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="http://schemas.xmlsoap.org/soap/encoding/" xmlns:tns="http://tempuri.org/" xmlns:types="http://tempuri.org/encodedTypes" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">  
    <soap:Body soap:encodingStyle="http://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>  

套用屬性至傳回值Applying Attributes to Return Values

您也可以套用屬性至傳回值以控制命名空間、項目名稱等等。You can also apply attributes to return values to control the namespace, element name, and so forth. 下列程式碼範例套用 XmlElementAttribute 屬性至 MyLiteralMethod 方法的傳回值。The following code example applies the XmlElementAttribute attribute to the return value of the MyLiteralMethod method. 這樣做可以讓您控制命名空間與項目名稱。Doing so allows you to control the namespace and element name.

<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  
[return: XmlElement(Namespace = "http://www.cohowinery.com",  
ElementName = "BookOrder")]  
[WebMethod][SoapDocumentMethod]  
public Order MyLiteralMethod(){  
    Order myOrder = new Order();  
    return myOrder;  
}  

叫用時,程式碼會傳回類似以下所示的 XML。When invoked, the code returns XML that resembles the following.

<?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="http://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>  

套用至參數的屬性Attributes Applied to Parameters

您也可以套用屬性至參數以指定命名空間、項目名稱等等。You can also apply attributes to parameters to specify namespace, element name and so forth. 下列程式碼範例加入參數至 MyLiteralMethodResponse 方法,並套用 XmlAttributeAttribute 屬性至參數。The following code example adds a parameter to the MyLiteralMethodResponse method, and applies the XmlAttributeAttribute attribute to the parameter. 項目名稱與命名空間都針對參數設定。The element name and namespace are both set for the parameter.

<WebMethod, SoapDocumentMethod> _  
public Function MyLiteralMethod(<XmlElement _  
("MyOrderID", Namespace:="http://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  
[return: XmlElement(Namespace = "http://www.cohowinery.com",  
ElementName = "BookOrder")]  
[WebMethod][SoapDocumentMethod]  
public Order MyLiteralMethod([XmlElement("MyOrderID",   
Namespace="http://www.microsoft.com")] string ID){  
    Order myOrder = new Order();  
    myOrder.OrderID = ID;  
    return myOrder;  
}   

SOAP 要求可能類似下列所示。The SOAP request would resemble the following.

<?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="http://schemas.xmlsoap.org/soap/envelope/">  
    <soap:Body>  
        <MyLiteralMethod xmlns="http://tempuri.org/">  
            <MyOrderID xmlns="http://www.microsoft.com">string</MyOrderID>  
        </MyLiteralMethod>  
    </soap:Body>  
</soap:Envelope>  

套用屬性至類別Applying Attributes to Classes

若您需要控制類別相互關聯之項目的命名空間,可在適當的情況下套用 XmlTypeAttributeXmlRootAttributeSoapTypeAttributeIf you need to control the namespace of elements that correlate to classes, you can apply XmlTypeAttribute, XmlRootAttribute, and SoapTypeAttribute, as appropriate. 下列程式碼範例將三者全套用至 Order 類別。The following code example applies all three to the Order class.

<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  
[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;  
}  

套用 XmlTypeAttributeSoapTypeAttribute 的結果可在檢查服務說明時看到,如下列程式碼範例所示。The results of applying the XmlTypeAttribute and SoapTypeAttribute can be seen when you examine the service description, as shown in the following code example.

    <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>  

XmlRootAttribute 的效果也可以在 HTTP GET 與 HTTP POST 結果中看到,如下所示。The effect of the XmlRootAttribute can also be seen in the HTTP GET and HTTP POST results, as follows.

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

另請參閱See also