SOAP 格式的 .NET Framework 支援

發行項
02/28/2011

本主題專門說明舊有技術。應該使用下列建立 XML Web Service 及 XML Web Service 用戶端： Windows Communication Foundation.

建立 ASP.NET Web 服務的開發人員可以將屬性套用至個別 Web 服務方法或整個 Web 服務類別，以指定這些 SOAP 格式，而不需要徒手製作 WSDL 文件。如果開發人員未指定這些屬性，將會使用預設的 SOAP 格式。

如果根據現有 WSDL 文件開發 Web 服務，您可以搭配 /server 選項執行 Wsdl.exe 工具，以產生自動設定適當屬性值的抽象 Web 服務類別。

如果不使用 /server 選項，Wsdl.exe 就會產生可將相關 SOAP 格式屬性設定為適當值的用戶端 Proxy 類別，以便與輸入 WSDL 文件所描述的 Web 服務進行通訊。用戶端 Proxy 類別會使用大部分可在伺服器上指定的相同屬性。一般而言，開發人員不需要在用戶端 Proxy 類別中手動新增或編輯這些屬性，因為 Wsdl.exe 通常會產生用戶端以確保其符合 WSDL 文件所指定的服務合約。

下表簡述使用 ASP.NET 和 .NET Framework 建立之 Web 服務和用戶端所支援的格式選項，以及完成每個特定組合的屬性。您可以將具有 Service 後置字元的屬性套用至實作 Web 服務 (而非用戶端 Proxy 類別) 的類別，來為類別中的 Web 服務方法設定預設的格式化樣式。您可以將具有 Method 後置字元的屬性套用至 Web 服務方法，或套用至呼叫 Web 服務方法之用戶端 Proxy 類別中的方法。下列段落將提供每個組合的詳細資訊。

參數格式 (用途)	以文件為主之 SOAP 訊息的 SOAP 本文格式 (樣式)	以 RPC 為主之 SOAP 訊息的 SOAP 本文格式 (樣式) (根據 SOAP 1.1 第 7s 節規格)
常值 (Literal)，此格式依據每個參數的 XSD 結構描述	SoapDocumentMethod 或SoapDocumentService Use=Literal 這是預設值。	SoapRpcMethod 或SoapRpcService Use=Literal
編碼 (Encoded)，此格式依據 SOAP 1.1 第 5 節編碼規則	SoapDocumentMethod 或SoapDocumentService Use=Encoded	SoapRpcMethod 或SoapRpcService Use=Encoded 這是預設值。

常值 (Literal)，此格式依據每個參數的 XSD 結構描述

SoapDocumentMethod 或SoapDocumentService

Use=Literal

這是預設值。

SoapRpcMethod 或SoapRpcService

Use=Literal

編碼 (Encoded)，此格式依據 SOAP 1.1 第 5 節編碼規則

SoapDocumentMethod 或SoapDocumentService

Use=Encoded

SoapRpcMethod 或SoapRpcService

Use=Encoded

這是預設值。

注意：
實際屬性名稱會使用 Attribute 後置字元。在原始程式碼中，您可以使用縮寫名稱，如上表所示。

控制整體 SOAP 本文格式

就樣式而言，它可以控制 Web 服務執行階段引擎是要套用 RPC 慣例，或是遵照 XML 文件的決定，而它在 ASP.NET Web 服務中的預設選擇為文件，而非 RPC。

透過將 SoapDocumentMethodAttribute 屬性套用至 Web 服務方法或用戶端 Proxy 方法的方式，或是將 SoapDocumentServiceAttribute 屬性套用至 Web 服務類別的方式，即可明確指定文件樣式。透過將 SoapRpcMethodAttribute**** 屬性套用至 Web 服務方法或用戶端 Proxy 方法的方式，或是將 SoapRpcServiceAttribute 屬性套用至 Web 服務類別的方式，即可明確指定 RPC 樣式。就服務而言，方法層級屬性會覆寫類別層級屬性。

上述這些屬性會在決定參數和傳回值格式時扮演角色，如本主題後段所述。而它們在決定是否於執行階段自動產生「包裝函式」項目以包含參數或傳回值時，也有一部分的影響力。如需詳細資訊，請參閱 HOW TO：控制額外項目中是否要包含 Web 服務方法參數.

如需詳細資訊如何套用這些屬性，請參閱 HOW TO：控制 Web 服務方法的整體 SOAP 主體格式。

控制參數和傳回值格式

就用途 (Use) 而言，它可以控制 Web 服務方法參數或傳回值的格式，其在文件樣式的 ASP.NET Web 服務中的預設選擇是常值 (Literal)。RPC 樣式 ASP.NET Web 服務的預設選項是編碼 (Encoded)。您可以在對應的 SoapDocumentMethodAttribute、SoapDocumentServiceAttribute、SoapRpcMethodAttribute 或 SoapRpcServiceAttribute 屬性 (Attribute) 上將 Use 屬性 (Property) 設為 SoapBindingUse.Literal 或 SoapBindingUse.Encoded，藉此變更 use 值。

如需詳細資訊如何設定Use 屬性，請參閱 HOW TO：針對 Web 服務方法控制參數及傳回值格式。

控制是否將參數放在額外的 XML 項目之中

Web 服務方法的參數或傳回值可以自動封裝在 SOAP 訊息 Body 項目的父 XML 項目中。開發人員不一定要指定父項目。如您所見，RPC 格式化樣式會完成這項工作。不過，這也是具有文件格式化樣式的選項。Web 服務基礎結構會在執行階段隱含地插入額外項目，並不需要在 WSDL 文件中指定父 XML 項目 (或包裝函式)。

這項慣例稱為「包裝」，可藉由將 SoapDocumentMethod.ParameterStyle 或 SoapDocumentService.ParameterStyle 屬性設為 SoapParameterStyle.Wrapped 的值來指定。Wrapped 也是預設值。

SoapParameterStyle 列舉具有可在服務類別層級上指定預設參數樣式的 Default 值，以及可關閉包裝且可將 WSDL 指定為訊息部分之 XML 項目逐一轉譯成方法參數和傳回值的 Bare 值。如果使用 Bare 參數樣式，每個參數或傳回值都會對應至指定的訊息部分。

選擇是否要包裝，並不是在 WSDL 文件中指定；同時使用 Wrapped 和 Bare，時，所使用的繫結樣式即是文件。更確切地說，這個選擇牽涉到 XML 和程式碼之間的繫結，或說牽涉到 WSDL 中定義的 XML 和方法的參數及傳回值之間的繫結。

如果將 ParameterStyle 屬性設定為 SoapParameterStyle.Bare，開發人員就能夠指定含有多個部分的訊息；實際上，即是多個以 SOAP Body 項目子系形式出現的 XML 項目。在技術上說，多個項目並不構成 XML 文件，因為文件必須有單一的根項目。因此，Web 服務社群中的建議做法是，搭配文件樣式服務來使用單一訊息部分。每個 Web 服務方法都必定不會使用其預定的簽章，而是會使用以對應至 XML 文件之物件當做單一參數而以對應至 XML 文件之另一物件當做傳回值的簽章。開發人員必須撰寫程式碼來擷取或封裝實際的參數或傳回值。

因此，開發人員通常只需將 ParameterStyle 屬性設為 SoapParameterStyle.Wrapped 即可，Web 服務基礎結構會將參數和傳回值放入 XML 文件。

如需詳細資訊如何設定 ParameterStyle 屬性，請參閱 HOW TO：控制額外項目中是否要包含 Web 服務方法參數。

設定整個 Web 服務的預設 SOAP 格式

如本主題先前所述，SoapDocumentServiceAttribute 和 SoapRpcServiceAttribute 屬性可以用來為整個 Web 服務類別設定樣式、用途及參數對應至文件之樣式的預設值，但無法對用戶端 Proxy 類別進行這種設定。SoapDocumentMethod 和 SoapRpcMethod 屬性可以用來覆寫每一個 Web 服務方法的服務層級設定。

如需詳細資訊如何使用 SoapDocumentService 和 SoapRpcService 屬性，請參閱 HOW TO：為整個 Web 服務修改預設 SOAP 格式。

使用 XML 序列化自訂 SOAP 訊息

除了指定樣式、用途和是否插入包裝函式項目之外，您還可以使用 XML 序列化直接自訂 SOAP 訊息中的 XML。根據預設，.NET Framework 的 Web 服務基礎結構會自動將公用欄位和屬性序列化為 XML 訊息。

System.Xml.Serialization 命名空間包含許多用來操作 XML 的屬性。下列程式碼範例示範如何將這其中的一些屬性直接套用至 Web 服務方法參數或傳回值。

[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

下面列出一些常用的屬性 (這些屬性的名稱沒有顯示 Attribute 後置字元，因為這是可以省略的)：

XmlElement：指定要將公用欄位或屬性序列化為 XML 項目。這是序列化非陣列公用欄位和屬性 (Property) 的預設屬性 (Attribute)。如果將 XmlElement 屬性套用至陣列型別屬性 (Attribute) 的公用欄位和屬性 (Property)，這個陣列就會在不使用特殊父項目的情況下，與其他成員一起序列化。
XmlAttribute：指定要將公用欄位或屬性 (Property) 序列化為表示包含型別 (Containing Type) 之項目的 XML 屬性 (Attribute)。
XmlArray：指定要使用特殊的父項目將陣列型別的公用欄位序列化。這是序列化陣列型別公用欄位和屬性 (Property) 的預設屬性 (Attribute)。
XmlArrayItem：在搭配 XmlArray 屬性的組合中用來控制陣列元素。
XmlIgnore：指定不將公用欄位或屬性序列化。

前述屬性 (XmlIgnore 除外) 除了預設值之外，還可以用來指定項目或屬性名稱，即非陣列成員的成員名稱。您也可以使用這些屬性來為特定項目指定命名空間。Web 服務通常不會混用命名空間，您只需在類別層級使用 WebService 或 WebServiceBinding 等屬性指定命名空間即可。

如需詳細資訊，請參閱，請參閱 System.Xml.Serialization。

注意：
就 RPC 或已編碼的 Web 服務而言，如果使用具有 SOAP 編碼的 RPC 樣式，將會在使用 XML 序列化時受到限制。參數和傳回值會自動出現，但是不限定命名空間。此外，與文件或 RPC 樣式搭配時，SOAP 1.1 第 5 節的編碼規格也會禁止將資料繫結至 XML 屬性。

注意：
如果抽象服務類別或用戶端 Proxy 類別是從 WSDL 文件中產生，則會自動為 WSDL types 項目中定義的 XML 結構描述項目和型別套用正確的 System.Xml.Serialization 屬性 (不論這些項目和型別是嵌入的或匯入的)。

注意：
在 Web 服務中使用可為 Null 的型別會產生含有型別設定 "nillable=true" 的 WSDL。不過，如果直接將可為 Null 的型別當做 Web 方法參數或傳回值使用，則產生的 WSDL 將無法在下列情況中反映是否允許 Null 型別：1) 使用以 RPC 為主的 SOAP 訊息時，以及 2) 在 Bare 模式下，搭配編碼的參數來使用以文件為主的 SOAP 訊息時。

在 Web 服務中使用可為 Null 的型別會產生含有型別設定 "nillable=true" 的 WSDL。不過，如果直接將可為 Null 的型別當做 Web 方法參數或傳回值使用，則產生的 WSDL 將無法在下列情況中反映是否允許 Null 型別：1) 使用以 RPC 為主的 SOAP 訊息時，以及 2) 在 Bare 模式下，搭配編碼的參數來使用以文件為主的 SOAP 訊息時。

如需詳細資訊如何使用 XmlElement 屬性，請參閱 HOW TO：使用 XML 序列化自訂 SOAP 訊息。

另請參閱

共用方式為