SOAP 格式的 .NET Framework 支援
本主題專門說明舊有技術。 應該使用下列建立 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 這是預設值。 |
注意: |
---|
實際屬性名稱會使用 Attribute 後置字元。在原始程式碼中,您可以使用縮寫名稱,如上表所示。 |
就樣式而言,它可以控制 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 服務方法控制參數及傳回值格式。
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 服務方法參數。
如本主題先前所述,SoapDocumentServiceAttribute 和 SoapRpcServiceAttribute 屬性可以用來為整個 Web 服務類別設定樣式、用途及參數對應至文件之樣式的預設值,但無法對用戶端 Proxy 類別進行這種設定。SoapDocumentMethod 和 SoapRpcMethod 屬性可以用來覆寫每一個 Web 服務方法的服務層級設定。
如需詳細資訊如何使用 SoapDocumentService 和 SoapRpcService 屬性,請參閱 HOW TO:為整個 Web 服務修改預設 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 訊息時。 |
如需詳細資訊如何使用 XmlElement 屬性,請參閱 HOW TO:使用 XML 序列化自訂 SOAP 訊息。
HOW TO:控制 Web 服務方法的整體 SOAP 主體格式
HOW TO:針對 Web 服務方法控制參數及傳回值格式
HOW TO:控制額外項目中是否要包含 Web 服務方法參數
HOW TO:為整個 Web 服務修改預設 SOAP 格式
HOW TO:使用 XML 序列化自訂 SOAP 訊息
System.Xml.Serialization
SoapDocumentMethodAttribute
SoapRpcMethodAttribute
SoapDocumentServiceAttribute
SoapRpcServiceAttribute