.NET Framework 对 SOAP 格式的支持

项目
02/28/2011

本主题专门介绍一项旧有技术。现在应通过使用以下链接来创建 XML Web 服务和 XML Web 服务客户端： Windows Communication Foundation.

为 ASP.NET 创建 Web 服务的开发人员可以通过向各个 Web 服务方法或者向整个 Web 服务类应用特性来指定这些 SOAP 格式，而不用手动创建 WSDL 文档。如果开发人员没有指定这些特性，则使用默认的 SOAP 格式。

如果您正在基于现有的 WSDL 文档开发 Web 服务，您可以用 /server 选项运行 Wsdl.exe 工具，以便生成一个相应特性值已自动设置的抽象 Web 服务类。

如果不使用 /server 选项，Wsdl.exe 会产生一个客户端代理类，该代理类将相关 SOAP 格式设置特性设置为适当的值，以便与输入 WSDL 文档所描述的 Web 服务进行通信。客户端代理类使用的多数特性与可在服务器上指定的特性相同。通常，开发人员无需在客户端代理类中手动添加或编辑这些特性，因为该客户端通常由 Wsdl.exe 生成以确保它符合 WSDL 文档指定的服务协定。

下表概述了使用 ASP.NET 和 .NET Framework 创建的 Web 服务和客户端所支持的格式设置选项，还概述了构成每种特定组合的特性。带有后缀 Service 的特性可以应用于实现 Web 服务的类（不是客户端代理类），以便为该类中的 Web 服务方法设置默认格式设置样式。带有后缀 Method 的特性可以应用于 Web 服务方法，或者应用于客户端代理类中调用 Web 服务方法的方法。将在下面的段落中介绍每种组合的详细信息。

参数格式设置（用法）	基于文档的 SOAP 消息的 SOAP 正文格式设置（样式）	符合 SOAP 1.1 第 7s 节要求的基于 RPC 的 SOAP 消息的 SOAP 正文格式设置（样式）
Literal - 基于每个参数的 XSD 架构	SoapDocumentMethod 或SoapDocumentService Use=Literal 这是默认选项。	SoapRpcMethod 或SoapRpcService Use=Literal
Encoded - SOAP 1.1 第 5 节的编码规则	SoapDocumentMethod 或SoapDocumentService Use=Encoded	SoapRpcMethod 或SoapRpcService Use=Encoded 这是默认选项。

参数格式设置（用法）

基于文档的 SOAP 消息的 SOAP 正文格式设置（样式）

符合 SOAP 1.1 第 7s 节要求的基于 RPC 的 SOAP 消息的 SOAP 正文格式设置（样式）

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 服务方法或客户端代理方法或者将 SoapDocumentServiceAttribute 特性应用于 Web 服务类，可以显式指定文档样式。通过将 SoapRpcMethodAttribute**** 特性应用于 Web 服务方法或客户端代理方法或者将 SoapRpcServiceAttribute 特性应用于 Web 服务类，可以显式指定 RPC 样式。对于服务，方法级特性将重写类级特性。

这些相同的特性在确定参数和返回值的格式设置时将发挥作用，如本主题后面所述。在确定是否在运行时自动生成一个“wrapper”元素以包含参数或返回值时，它们也发挥一定的作用。有关更多信息，请参见如何：控制 Web 服务方法参数是否包含在额外的元素中.

有关如何应用这些特性的更多信息，请参见如何：控制 Web 服务方法的整体 SOAP 正文格式设置。

控制参数和返回值的格式设置

对于 use（控制 Web 服务方法参数或返回值的格式设置），文档样式 ASP.NET Web 服务中的默认选项是 literal。RPC 样式 ASP.NET Web 服务中的默认选项是 encoded。通过将 SoapDocumentMethodAttribute、SoapDocumentServiceAttribute、SoapRpcMethodAttribute 或 SoapRpcServiceAttribute 特性上的 Use 属性设置为 SoapBindingUse.Literal 或 SoapBindingUse.Encoded，可以更改 use 值。

有关如何设置 Use 属性的更多信息，请参见如何：控制 Web 服务方法的参数和返回值的格式设置。

控制参数是否包含在额外 XML 元素内

可以将 Web 服务方法的参数或返回值自动封装在 SOAP 消息的 Body 元素内的父 XML 元素中。开发人员不必指定该父元素。如您所见，RPC 格式设置样式会执行此操作。但是，它也是文档格式设置样式的选项。Web 服务基础结构在运行时隐式插入在 WSDL 文档中指定的额外元素，而不是插入父 XML 元素或包装。

此约定称为“包装”，可以通过将 SoapDocumentMethod.ParameterStyle 或 SoapDocumentService.ParameterStyle 属性设置为 SoapParameterStyle.Wrapped 值来指定。Wrapped 还是默认值。

SoapParameterStyle 枚举还有两个值：Default 和 Bare，前者用于在服务类级别指定默认的参数样式，后者用于关闭包装并严格地将 WSDL 指定为消息部分的 XML 元素转换为方法参数和返回值。通过 Bare 参数样式，每个参数或返回值对应于一个指定的消息部分。

是否进行包装的选项不在 WSDL 文档中指定；同时使用 Wrapped 和 Bare，使用的绑定样式是文档。更确切地说，该选项涉及 XML 与代码之间，即 WSDL 中定义的 XML 与方法的参数及返回值之间的绑定。

将 ParameterStyle 属性设置为 SoapParameterStyle.Bare 时，开发人员可以指定具有多个部分（准确地说是作为 SOAP Body 元素的子级出现的多个 XML 元素）的消息。从技术角度看，多个元素不可以构成一个 XML 文档，因为一个文档必须要有一个根元素。因此，Web 服务社区中推荐的做法是对文档样式服务使用单个消息部分。每个 Web 服务方法必须不得使用其专用签名，而是使用以映射到 XML 文档的一个对象作为单个参数并以映射到 XML 文档的另一个对象作为返回值的签名。开发人员必须编写代码以提取或打包真正的参数或返回值。

因此，一般情况下，开发人员将 ParameterStyle 属性设置为 SoapParameterStyle.Wrapped 就足够了，而由 Web 服务基础结构将参数和返回值放入 XML 文档中。

有关如何设置 ParameterStyle 属性的更多信息，请参见如何：控制 Web 服务方法参数是否包含在额外的元素中。

设置整个 Web 服务的默认 SOAP 格式设置

如本主题前面部分所述，SoapDocumentServiceAttribute 和 SoapRpcServiceAttribute 特性可用于为整个 Web 服务类设置样式、用法和参数到文档映射样式的默认值，但不为客户端代理类设置。可以使用 SoapDocumentMethod 和 SoapRpcMethod 特性为每个 Web 服务方法重写服务级别设置。

有关如何使用 SoapDocumentService 和 SoapRpcService 特性的更多信息，请参见如何：修改整个 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 元素。这是用来序列化非数组公共字段和属性的默认特性。当 XmlElement 特性应用于数组类型特性的公共字段和属性时，该数组可在没有特殊的父元素的情况下与其他成员同时序列化。
XmlAttribute：指定将公共字段或属性序列化为表示包含类型的元素的 XML 特性。
XmlArray：指定使用特殊的父元素序列化数组类型的公共字段。这是用来序列化数组类型的公共字段和属性的默认特性。
XmlArrayItem：与 XmlArray 特性结合使用来控制数组元素。
XmlIgnore：指定不对公共字段或属性进行序列化。

以上特性（不包括 XmlIgnore）可用来指定除默认值以外的元素名称或特性名称，即非数组成员的成员名称。还可以用这些特性来指定特定元素的命名空间。通常，Web 服务不混合命名空间，并且只需使用 WebService 或 WebServiceBinding 之类的特性在类级别指定命名空间。

有关更多信息，请参见，请参见 System.Xml.Serialization。

注意：
对于 RPC 或编码 Web 服务（应用了包含 SOAP 编码的 RPC 样式），XML 序列化的使用受到限制。参数和返回值自动显示，且不具有命名空间限定。此外，SOAP 1.1 第 5 节与文档或 RPC 样式相组合的编码禁止将数据绑定到 XML 特性。

注意：
如果抽象服务类或客户端代理类是从 WSDL 文档生成的，则会自动为 WSDL types 元素之下定义的 XML 架构元素和类型应用正确的 System.Xml.Serialization 特性，而不管它们显示为内联还是被导入。

注意：
在 Web 服务中使用可以为 null 的类型会产生 WSDL，其中包含该类型的“nillable=true”设置。但是，将可以为 null 的类型直接用作 Web 方法的参数或返回值时，在以下两种情况下可空性不会在产生的 WSDL 中反映出来：1) 使用基于 RPC 的 SOAP 消息时，2) 在 Bare 模式中结合使用基于文档的 SOAP 消息和编码参数时。

在 Web 服务中使用可以为 null 的类型会产生 WSDL，其中包含该类型的“nillable=true”设置。但是，将可以为 null 的类型直接用作 Web 方法的参数或返回值时，在以下两种情况下可空性不会在产生的 WSDL 中反映出来：1) 使用基于 RPC 的 SOAP 消息时，2) 在 Bare 模式中结合使用基于文档的 SOAP 消息和编码参数时。

有关如何使用 XmlElement 特性的更多信息，请参见如何：使用 XML 序列化自定义 SOAP 消息。

另请参见