How to: Control the Overall SOAP Body Formatting for a Web Service Method

2011-02-13

This topic is specific to a legacy technology. XML Web services and XML Web service clients should now be created using Windows Communication Foundation.

For overall SOAP body formatting, or style, the Web Services Description Language (WSDL) provides two choices: RPC and document. The .NET Framework controls these choices in code using attributes.

To specify a Document formatting style

Apply a SoapDocumentMethod attribute or a SoapRpcMethod attribute to the method in the proxy class calling the applicable Web service method.

Web services created using ASP.NET support the use of both the Literal and Encoded parameter formatting styles. The following example combines the Document method formatting style with the Literal parameter formatting style.

[SoapDocumentMethod("https://www.contoso.com/DocumentWrappedLiteral",
                    RequestNamespace="https://www.contoso.com",
                    ResponseNamespace="https://www.contoso.com",
                    Use=SoapBindingUse.Literal)]
public string DocumentWrappedLiteral(Address MyAddress, 
                                     bool useZipPlus4) {

<SoapDocumentMethod("https://www.contoso.com/DocumentWrappedLiteral", _
                    RequestNamespace:="https://www.contoso.com", _
                    ResponseNamespace:="https://www.contoso.com", _
                    Use:=SoapBindingUse.Literal)> _
   Public Function DocumentWrappedLiteral(ByVal MyAddress As Address, _
                             ByVal useZipPlus4 As Boolean)As String

With the Document formatting style, an XSD schema is defined within the service description that defines both the SOAP request and SOAP response. The following is an excerpt from the service description for the SOAP request for the DocumentWrappedLiteral Web service method. Because the first parameter to the DocumentWrappedLiteral Web service method is a class, and the Literal parameter formatting style was specified, an XSD schema is created for the address type.

<s:element name="DocumentWrappedLiteral">
  <s:complexType>
    <s:sequence>
       <s:element minOccurs="1" maxOccurs="1" name="MyAddress"
                  nillable="true" type="s0:Address" /> 
       <s:element minOccurs="1" maxOccurs="1" name="useZipPlus4"
                  type="s:boolean" /> 
    </s:sequence>
  </s:complexType>
</s:element>

<s:complexType name="Address">
   <s:sequence>
      <s:element minOccurs="1" maxOccurs="1" name="Street"
                 nillable="true" type="s:string" /> 
      <s:element minOccurs="1" maxOccurs="1" name="City"
                 nillable="true" type="s:string" /> 
      <s:element minOccurs="1" maxOccurs="1" name="Zip" nillable="true"
                 type="s:string" /> 
   </s:sequence>
</s:complexType>

With the XSD schema that is defined in the service description, the XML portion of the SOAP request to the DocumentWrappedLiteral Service method follows. Note that the XML elements beneath the Body element in the SOAP request match the elements defined in the XSD schema.

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xmlns:xsd="http://www.w3.org/2001/XMLSchema"
               xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <DocumentWrappedLiteral xmlns="https://www.contoso.com">
      <MyAddress>
        <Street>string</Street>
        <City>string</City>
        <Zip>string</Zip>
      </MyAddress>
      <useZipPlus4>boolean</useZipPlus4>
    </DocumentWrappedLiteral>
  </soap:Body>
</soap:Envelope>

To specify RPC formatting style

Apply a SoapRpcMethod attribute to the method in the proxy class calling the applicable Web service method.

[SoapRpcMethodAttribute("https://www.contoso.com/Rpc",
                        RequestNamespace="https://www.contoso.com",
                        ResponseNamespace="https://www.contoso.com")]
public Address Rpc(Address address, bool useZipPlus4) {

<SoapRpcMethodAttribute("https://www.contoso.com/Rpc", _
                        RequestNamespace:="https://www.contoso.com", _
                        ResponseNamespace:="https://www.contoso.com")> _
Public Function Rpc(ByVal address As Address, _
                    ByVal useZipPlus4 As Boolean) As Address

An XSD schema is not strictly defined in the service description for either the SOAP request or SOAP response to the Rpc method in the previous example, but rather just the parts that comprise them. Therefore, look at the SOAP request for the Rpc method, noting that the parameters are encapsulated inside one element and they are encoded using the Encoded parameter formatting.

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:xsd="http://www.w3.org/2001/XMLSchema"
             xmlns:soapenc="https://schemas.xmlsoap.org/soap/encoding/"
             xmlns:tns="https://www.contoso.com"
             xmlns:tnsTypes="https://www.contoso.com/encodedTypes"
             xmlns:wsdl="https://schemas.xmlsoap.org/wsdl/"
             xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body soap:encodingStyle="https://schemas.xmlsoap.org/soap/encoding/">
    <tns:Rpc>
      <address href="#1" />
      <useZipPlus4>boolean</useZipPlus4>
    </tns:Rpc>
    <tnsTypes:Address id="1">
      <Street id="2">string</Street>
      <City id="3">string</City>
      <Zip id="4">string</Zip>
    </tnsTypes:Address>
  </soap:Body>
</soap:Envelope>

Share via

How to: Control the Overall SOAP Body Formatting for a Web Service Method

To specify a Document formatting style

To specify RPC formatting style

See Also

Reference

Other Resources

Additional resources