.NET Framework 对 SOAP 格式的支持

项目
12/31/2007

为 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 这是默认值。	支持。
Encoded - SOAP 1.1 第 5 节的编码规则	SoapDocumentMethod 或 SoapDocumentService Use=Encoded	SoapRpcMethod 或 SoapRpcService

参数格式设置（用法）

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

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

Literal - 基于每个参数的 XSD 架构

SoapDocumentMethod 或 SoapDocumentService

Use=Literal

这是默认值。

支持。

Encoded - SOAP 1.1 第 5 节的编码规则

SoapDocumentMethod 或 SoapDocumentService

Use=Encoded

SoapRpcMethod 或 SoapRpcService

注意实际的属性名使用后缀 Attribute。在源代码中，这些名称可以采用缩写形式，如上表所示。

控制整体 SOAP 正文格式设置

对于样式（控制 Web 服务运行时引擎是应用 RPC 约定还是遵从 XML 文档），ASP.NET Web 服务中的默认选项是文档而非 RPC。

通过将 SoapDocumentMethod 属性应用于 Web 服务方法或客户端代理方法或者将 SoapDocumentService 属性应用于 Web 服务类，可以显式指定文档样式。通过将 SoapRpcMethod 属性应用于 Web 服务方法或客户端代理方法或者将 SoapRpcService 属性应用于 Web 服务类，可以显式指定 RPC 样式。对于服务，方法级属性将重写类级属性。

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

主题如何：控制 Web 服务方法的整体 SOAP 正文格式设置提供了有关如何应用这些属性的说明。

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

对于用法（控制 Web 服务方法参数或返回值的格式设置），ASP.NET Web 服务中的默认选项是 literal 而非 SOAP encoded。

但是，该选项还依赖于样式选项，涉及 SOAP Body 元素的第一级内容（并有可能涉及其第二级内容）的格式设置。如果 Web 服务方法或对应的代理类方法使用 SoapRpcMethod 属性，则会自动使用 SOAP 编码。 .NET Framework 确实支持 RPC/literal 组合。当 SoapRpcService 属性应用于 Web 服务类且未被应用于给定 Web 服务方法的 SoapDocumentMethod 属性重写时，情况也是如此。另一方面，SoapDocumentMethod 和 SoapDocumentService 属性 (Attribute) 具有一个可能值为 SoapBindingUse.Literal 和 SoapBindingUse.Encoded 的 Use 属性 (Property)。

主题如何：控制 Web 服务方法的参数和返回值的格式设置提供了有关如何设置 Use 属性的说明。

控制参数是否包含在额外 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 文档中。

主题如何：控制 Web 服务方法参数是否包含在额外的元素中提供了有关如何设置 ParameterStyle 属性的说明。

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

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

主题如何：修改整个 Web 服务的默认 SOAP 格式设置提供了有关如何使用 SoapDocumentService 和 SoapRpcService 属性的说明。

使用 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) 应用于数组类型属性 (Attribute) 的公共字段和属性 (Property) 时，该数组可在没有特殊的父元素的情况下与其他成员同时序列化。
XmlAttribute：指定将公共字段或属性 (Property) 序列化为表示包含类型的元素的 XML 属性 (Attribute)。
XmlArray：指定使用特殊的父元素序列化数组类型的公共字段。这是用来序列化数组类型的公共字段和属性 (Property) 的默认属性 (Attribute)。
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 消息和编码参数时。

主题如何：使用 XML 序列化自定义 SOAP 消息提供了有关如何使用 XmlElement 属性的说明。

请参见

Footer image

通过