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.

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.

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.

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.

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(
     "http://www.contoso.com/DocumentBareLiteral",
     Use=SoapBindingUse.Literal,
     ParameterStyle=SoapParameterStyle.Bare)]
[return: XmlElement(Namespace="http://www.contoso.com",
                    IsNullable=true)]
public string DocumentBareLiteral(
   [XmlElement(Namespace="http://www.contoso.com",
                     IsNullable=true)] 
   Address1 MyAddress, 
   [XmlElement(Namespace="http://www.contoso.com",
            IsNullable=false)] 
   bool useZipPlus4) {

<SoapDocumentMethod( _
     http://www.contoso.com/DocumentBareLiteral", _
     Use:=SoapBindingUse.Literal, _
     ParameterStyle:= SoapParameterStyle.Bare)> _
Public Function DocumentBareLiteral( _
   ByVal <XmlElement([Namespace]:="http://www.contoso.com", _
                      IsNullable:=true)> _
   MyAddress As Address1, _
   ByVal <XmlElement([Namespace]:="http://www.contoso.com", _
                      IsNullable:=false)> _
   useZipPlus4 As Boolean) _
   As <XmlElement([Namespace]:="http://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.