How to: Control Parameter and Return Value Formatting for a Web Service Method

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 the formatting of XML elements corresponding to method parameters and return values, or use, the Web Services Description Language (WSDL) provides two choices: SOAP encoded and literal. The .NET Framework controls these choices in code using attributes. Although ASP.NET provides an extensive architecture for controlling how the XML is formatted, the order in which parameters are serialized is not guaranteed.

To specify Literal parameter formatting

1. Apply a SoapDocumentMethod attribute to a method in the proxy class, setting the Use property to SoapBindingUse.Literal.

   The SoapBindingUse enumeration specifies the parameter formatting styles available to a Web service created using ASP.NET.

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

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

   The XML portion of the SOAP request to the DocumentLiteral Web service method follows. The parameters reside within the Body element and are encoded as self-containing XML documents, as they refer to an 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>
       <DocumentLiteral xmlns="https://www.contoso.com">
         <address>
           <Street>One Microsoft Way</Street>
           <City>Redmond</City>
           <Zip>98052</Zip>
         </address>
         <useZipPlus4>True</useZipPlus4>
       </DocumentLiteral>
     </soap:Body>
   </soap:Envelope>
   

To specify an Encoded parameter formatting

1. Apply a SoapDocumentMethod attribute or a SoapRpcMethod attribute to the method in the proxy class, setting the Use property to SoapBindingUse.Encoded.

   Unlike the Literal parameter formatting style, the Encoded parameter formatting style can be used in conjunction with both Web service method formatting styles. For more details on Web service method formatting styles see .NET Framework Support for SOAP Formats

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

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

   The XML portion of the SOAP request to the DocumentEncoded service method follows. Notice how the parameters are represented much differently than the Literal formatting style, as they are formatted using the encoding rules outlined in Section 5 of the SOAP specification. Pay particular attention to the address parameter, which is not a simple data type.

   <?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/">
       <tnsTypes:DocumentEncoded>
         <address href="#1" />
         <useZipPlus4>boolean</useZipPlus4>
       </tnsTypes:DocumentEncoded>
       <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>
   

See Also

Reference

SoapDocumentMethodAttribute
SoapRpcMethodAttribute

Other Resources

Customizing SOAP Message Formatting