.NET Framework Support for SOAP Formats

Article
11/03/2006

Instead of handcrafting a WSDL document, a developer creating a Web service for ASP.NET can specify these SOAP formats by applying attributes to either individual Web service methods or entire Web service classes. If a developer does not specify these attributes, the default SOAP formats are used.

If you are developing a Web service based on an existing WSDL document, you can run the Wsdl.exe tool with the /server option to generate an abstract Web service class that has the appropriate attribute values automatically set.

Without the /server option, Wsdl.exe produces a client proxy class that sets the relevant SOAP formatting attributes to the appropriate values to communicate with the Web service described by the input WSDL document. A client proxy class uses most of the same attributes that can be specified on the server. Normally, a developer does not need to manually add or edit these attributes in the client proxy class because normally the client is generated by Wsdl.exe to ensure that it complies with the service contract specified by the WSDL document.

The following table outlines the formatting choices supported by Web services and clients created using ASP.NET and the .NET Framework, along with the attributes that accomplish each specific combination. The attributes with a Service suffix can be applied to a class that implements a Web service (not a client proxy class) to set the default formatting style for Web service methods within the class. The attributes with a Method suffix can be applied either to a Web service method or to a method in a client proxy class that calls a Web service method. The details of each combination are covered in the following paragraphs.

Parameter formatting (use)	SOAP Body formatting (style) for Document-based SOAP messages	SOAP Body formatting (style) for RPC-based SOAP messages according to SOAP 1.1 Section 7s
Literal — based on an XSD schema for each parameter	SoapDocumentMethod or SoapDocumentService Use=Literal This is the default.	Not supported.
Encoded - SOAP 1.1 Section 5 encoding rules	SoapDocumentMethod or SoapDocumentService Use=Encoded	SoapRpcMethod or SoapRpcService

Literal — based on an XSD schema for each parameter

SoapDocumentMethod or SoapDocumentService

Use=Literal

This is the default.

Not supported.

Encoded - SOAP 1.1 Section 5 encoding rules

SoapDocumentMethod or SoapDocumentService

Use=Encoded

SoapRpcMethod or SoapRpcService

Note The actual attribute names use the Attribute suffix. In the source code, the names can be abbreviated, as shown in the preceding table.

Controlling the Overall SOAP Body Formatting

For style, which controls whether the Web service run-time engine applies the RPC conventions or defers to XML documents, the default choice in an ASP.NET Web service is document, not RPC.

Document style can be explicitly specified by applying the SoapDocumentMethod attribute to a Web service method or client proxy method, or by applying the SoapDocumentService attribute to a Web service class. RPC style can be explicitly specified by applying the SoapRpcMethod attribute to a Web service method or client proxy method, or by applying the SoapRpcService attribute to a Web service class. For a service, a method-level attribute overrides a class-level attribute.

These same attributes play a role in determining parameter and return value formatting, as described under the next heading. They also play a role in determining whether a "wrapper" element is automatically generated at run-time to contain the parameters or return value. See the topic How to: Control Whether Web Service Method Parameters Are Enclosed in an Extra Element.

The topic, How to: Control the Overall SOAP Body Formatting for a Web Service Method, provides instructions on applying these attributes.

Controlling the Parameter and Return Value Formatting

For use, which controls the formatting of the Web service method parameters or a return value, the default choice in an ASP.NET Web service is literal, not SOAP encoded.

However, the choice also hinges on the choice for style, concerning the formatting of the first and possibly second level contents of the SOAP Body element. If a Web service method, or the corresponding proxy class method, uses a SoapRpcMethod attribute, SOAP encoding is used automatically. The .NET Framework does not support the RPC/literal combination. The same is true if a SoapRpcService attribute is applied to the Web service class and it is not overridden by a SoapDocumentMethod attribute applied to a given Web service method. The SoapDocumentMethod and SoapDocumentService attributes, on the other hand, have a Use property whose possible values are SoapBindingUse.Literal and SoapBindingUse.Encoded.

The topic, How to: Control Parameter and Return Value Formatting for a Web Service Method, provides instructions on setting the Use property.

Controlling Whether Parameters Are Enclosed in an Extra XML Element

The parameters or return value for a Web service method can automatically be encapsulated within a parent XML element within the Body element of the SOAP message. The developer does not have to specify the parent element. As you have seen, RPC formatting style does this. However, it is also an option with a document formatting style. Instead of the parent XML element, or wrapper, being specified in the WSDL document, the extra element is implicitly inserted by the Web services infrastructure at run-time.

This convention is called wrapping and can be specified by setting the SoapDocumentMethod.ParameterStyle or SoapDocumentService.ParameterStyle property to a value of SoapParameterStyle.Wrapped. Wrapped is also the default value.

The SoapParameterStyle enumeration also has a value of Default to specify the default parameter style on the service class level, plus a value of Bare to turn off wrapping and literally translate the XML elements that are specified by the WSDL as message parts into method parameters and return values. With a Bare parameter style, each parameter or return value corresponds to a specified message part.

The choice of whether to wrap is not specified in a WSDL document; with both Wrapped and Bare, the binding style being used is document. Rather, the choice involves the binding between XML and code—between the XML defined in the WSDL and the parameters and return values of methods.

With the ParameterStyle property set to SoapParameterStyle.Bare, the developer is able to specify a message that has multiple parts—literally multiple XML elements appearing as children of the SOAP Body element. Technically, multiple elements do not constitute an XML document because a document must have a single root. Therefore, the recommended practice in the Web services community is to use a single message part with document-style services. Each Web service method must use not its intended signature but a signature where an object mapping to an XML document is the single parameter and another object mapping to an XML document is the return value. A developer must go to the trouble of writing code to extract or package the true parameters or return values.

Therefore, normally it is sufficient for a developer to set the ParameterStyle property to SoapParameterStyle.Wrapped and let the Web services infrastructure worry about placing parameters and return values into XML documents.

The topic, How to: Control Whether Web Service Method Parameters Are Enclosed in an Extra Element, provides instructions on setting the ParameterStyle property.

Setting the Default SOAP Formatting for an Entire Web Service

As noted earlier in this topic, the SoapDocumentServiceAttribute and SoapRpcServiceAttribute attributes can be used to set default values for style, use and parameter-to-document mapping style for an entire Web service class, but not for a client proxy class. The SoapDocumentMethod and SoapRpcMethod attributes can be used to override service-level settings on a per-Web service method basis.

The topic, How to: Modify the Default SOAP Formatting for an Entire Web Service, provides instructions on using the SoapDocumentService and SoapRpcService attributes.

Customizing SOAP Messages with XML Serialization

Besides specifying style, use, and whether to insert a wrapper element, you can directly customize the XML in a SOAP message with XML serialization. By default, the .NET Framework's Web services infrastructure automatically serializes public fields and properties into XML messages.

The System.Xml.Serialization namespace includes numerous attributes for manipulating XML. The following code example shows how some of these attributes can be applied directly to Web service method parameters or return values.

[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

Some commonly used attributes are listed as follows, their names appearing without the Attribute suffix, which can be omitted:

XmlElement: Specifies that a public field or property be serialized as an XML element. This is the default attribute for serializing non-array public fields and properties. When the XmlElement attribute is applied to public fields and properties of an array type attribute, the array is serialized alongside other members, without a special parent element.
XmlAttribute: Specifies that a public field or property be serialized as an XML attribute of the element that represents the containing type.
XmlArray: Specifies that a public field of an array type be serialized with a special parent element. This is the default attribute for serializing public fields and properties of an array type.
XmlArrayItem: Used in combination with the XmlArray attribute to control the array elements.
XmlIgnore: Specifies that a public field or property not be serialized.

The preceding attributes, except for XmlIgnore, can also be used to specify an element or attribute name besides the default, which is the member name for non-array members. They can also be used to specify a namespace for a particular element. Usually, a Web service does not mix namespaces and a namespace need only be specified at the class level, using an attribute like WebService or WebServiceBinding.

For more details, see System.Xml.Serialization.

Note

For RPC or encoded Web services, with RPC style with SOAP encoding, the use of XML serialization is restricted. Parameters and return values automatically appear without namespace qualification. Also, SOAP 1.1 Section 5 encoding, combined with document or RPC style, prohibits the binding of data to XML attributes.

Note

If an abstract service class or client proxy class is generated from a WSDL document, the correct System.Xml.Serialization attributes are automatically applied for the XML Schema elements and types that are defined under the WSDL types element, whether they appear inline or are imported.

Note

Using Nullable types in a web service results in WSDL that contains the "nillable=true" setting for the type. However, when Nullable types are used directly as web method parameters or return values, the nullability will not be reflected in the resulting WSDL in the following cases: 1) When RPC-based SOAP messages are used, and 2) When Document-based SOAP messages are used with encoded parameters in the bare mode.

The topic, How to: Customize SOAP Messages with XML Serialization, provides instructions on using the XmlElement attribute.

Share via

.NET Framework Support for SOAP Formats

Controlling the Overall SOAP Body Formatting

Controlling the Parameter and Return Value Formatting

Controlling Whether Parameters Are Enclosed in an Extra XML Element

Setting the Default SOAP Formatting for an Entire Web Service

Customizing SOAP Messages with XML Serialization

See Also

Tasks

Reference

Concepts

Additional resources