.NET Framework Support for SOAP Formats
This topic is specific to a legacy technology. XML Web services and XML Web service clients should now be created using Windows Communication Foundation.
Instead of handcrafting a WSDL document, a developer that creates 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. |
SoapRpcMethod or SoapRpcService Use=Literal |
Encoded - SOAP 1.1 Section 5 encoding rules |
SoapDocumentMethod or SoapDocumentService Use=Encoded |
SoapRpcMethod or SoapRpcService Use=Encoded This is the default. |
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 SoapDocumentMethodAttribute attribute to a Web service method or client proxy method, or by applying the SoapDocumentServiceAttribute attribute to a Web service class. RPC style can be explicitly specified by applying the SoapRpcMethodAttribute attribute to a Web service method or client proxy method, or by applying the SoapRpcServiceAttribute 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 later in this topic. They also play a role in determining whether a "wrapper" element is automatically generated at runtime to contain the parameters or return value. For more information, see How to: Control Whether Web Service Method Parameters Are Enclosed in an Extra Element.
For more information about how to apply these attributes, see How to: Control the Overall SOAP Body Formatting for a Web Service Method.
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 a document-style ASP.NET Web service is literal. The default choice in an RPC-style ASP.NET Web service is encoded. You can change the use value by setting the Use property on the corresponding SoapDocumentMethodAttribute, SoapDocumentServiceAttribute, SoapRpcMethodAttribute or SoapRpcServiceAttribute attributes to either SoapBindingUse.Literal or SoapBindingUse.Encoded.
For more information about how to set the Use property, see How to: Control Parameter and Return Value Formatting for a Web Service Method.
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 runtime.
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 that appear 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 write the 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 place parameters and return values into XML documents.
For more information about how to set the ParameterStyle property, see How to: Control Whether Web Service Method Parameters Are Enclosed in an Extra Element.
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 for each Web service method.
For more information about how to use the SoapDocumentService and SoapRpcService attributes, see How to: Modify the Default SOAP Formatting for an Entire Web Service.
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 appear 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 with 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 is required to be specified only at the class level, using an attribute like WebService or WebServiceBinding.
For more information, see , see System.Xml.Serialization.
Note
For RPC or encoded Web services, using 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 is not 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.
For more information about how to use the XmlElement attribute, see How to: Customize SOAP Messages with XML Serialization.
See Also
Tasks
How to: Control the Overall SOAP Body Formatting for a Web Service Method
How to: Control Parameter and Return Value Formatting for a Web Service Method
How to: Control Whether Web Service Method Parameters Are Enclosed in an Extra Element
How to: Modify the Default SOAP Formatting for an Entire Web Service
How to: Customize SOAP Messages with XML Serialization
Reference
System.Xml.Serialization
SoapDocumentMethodAttribute
SoapRpcMethodAttribute
SoapDocumentServiceAttribute
SoapRpcServiceAttribute
Concepts
SOAP Message Modification Using SOAP Extensions
Building XML Web Service Clients