Export (0) Print
Expand All

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

[Note: This topic is pre-release documentation and is subject to change in future releases. Blank topics are included as placeholders.]

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

  • 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(
        "http://www.contoso.com/DocumentLiteral",
        RequestNamespace="http://www.contoso.com",
        ResponseNamespace="http://www.contoso.com",
        Use=SoapBindingUse.Literal)]
    public string DocumentLiteral(Address1 address, bool useZipPlus4) {
    

    <SoapDocumentMethod( _
       "http://www.contoso.com/DocumentLiteral", _
       RequestNamespace:="http://www.contoso.com", _
       ResponseNamespace:="http://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="http://schemas.xmlsoap.org/soap/envelope/">
      <soap:Body>
        <DocumentLiteral xmlns="http://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

  • 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("http://www.contoso.com/DocumentEncoded",
                        RequestNamespace="http://www.contoso.com",
                        ResponseNamespace="http://www.contoso.com",
                        Use=SoapBindingUse.Encoded)]
    public string DocumentEncoded(Address address, bool useZipPlus4) {
    

    <SoapDocumentMethod("http://www.contoso.com/DocumentEncoded", _
                        RequestNamespace:="http://www.contoso.com", _
                        ResponseNamespace:="http://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="http://schemas.xmlsoap.org/soap/encoding/"
    xmlns:tns="http://www.contoso.com"
    xmlns:tnsTypes="http://www.contoso.com/encodedTypes"
    xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
    xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
      <soap:Body soap:encodingStyle="http://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>
    
Show:
© 2015 Microsoft