Customizing SOAP Messages

For XML Web services created using ASP.NET and their clients using SOAP to communicate with XML Web service methods, a sophisticated mechanism is available for controlling the format of the SOAP message sent to and expected from the server. SOAP dictates that the contents of the SOAP message sent to and from an XML Web service must be in XML. However, it does not strictly outline the formatting of the XML. To provide a mechanism for working with XML Web services that expect different formatting, ASP.NET provides an attribute-based mechanism for controlling the format of the XML in the SOAP message. In addition, an attribute-based mechanism for specifying the specific element and attribute names of the SOAP sent over the network is available for controlling the SOAP at a finer level of detail.

Communication between XML Web services and their clients is dictated in a large part by two industry standards: SOAP and the Web Services Description Language (WSDL). SOAP defines a formatting scheme for the data that appears beneath the Body element and a formatting scheme for how parameters are formatted within that Body element. The former is referred to as SOAP section 7 or simply RPC. For details on the SOAP specification, see the W3C Web site (http://www.w3.org/TR/SOAP). The latter is referred to as SOAP section 5 or simply Encoded. WSDL, which is used to describe the SOAP messages expected by an XML Web service, allows XML Web services to state that they accept RPC messages with encoded parameters, but it also defines two other terms: Literal and Document. Literal, like encoded, refers to how the parameters are formatted. Document, like RPC, refers to how the overall Body element is formatted.

Customizing the SOAP Sent by an XML Web Service Client

The following table outlines the formatting styles supported by XML Web services created using ASP.NET and the attributes that accomplish each specific combination. The attributes with a Service suffix can be applied to a class implementing an XML Web service to set the default formatting style for XML Web service methods within the class. The attributes with a Method suffix can be applied to only an XML Web service method or to a method in a proxy class calling an XML Web service method. The details of each combination are covered in the following paragraphs.

   Overall SOAP Body formatting
Parameter formattingDocument-based SOAP messagesRPC-based SOAP messages according to SOAP Section 7
Literal — based on an XSD schema for each parameterSoapDocumentMethod or SoapDocumentService

Use=Literal

This is the default.

Not supported.
Encoded - SOAP Section 5 encoding rulesSoapDocumentMethod or SoapDocumentService

Use=Encoded

SoapRpcMethod or SoapRpcService

Modifying the Parameter Formatting

One of the first decisions to make when you design an XML Web service is how you want the XML within the SOAP request to be encoded. Specifically, do you want the XML document to strictly follow an XSD schema or to follow formatting rules outlined in the SOAP specification in sections 5 and 7? The formatting rules of the SOAP specification in sections 5 and 7 allow for variations. Thus, a recipient of a SOAP request using the SOAP encoding rules must handle all the possible variations. By defining an XSD schema for the XML Web service method, exactly what needs to be sent in a SOAP request can be concretely defined. The default for XML Web services created using ASP.NET is to use document passing based on schemas.

Since the parameters to an XML Web service method can make up the majority of the data passed in a SOAP request or response, how the parameters are mapped to XML elements determines how the XML document will look. The Web Services Description Language (WSDL) defines two formatting styles for parameters: Encoded and Literal. Encoded refers to formatting the parameters using the SOAP encoding outlined in the SOAP specification in Section 5. Literal refers to mapping the parameters to XML elements using a predefined XSD schema for each parameter.

With an XML Web service client, you can choose how the parameters are mapped to XML elements to match what the XML Web service is expecting. XML Web services support both the Literal and Encoded parameter formatting styles. This support varies, depending on the XML Web service method formatting choice. For more information, see Modifying the Overall SOAP BODY Formatting.

Note that 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 an XML 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) {
    [Visual Basic]
    <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 XML 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

  • 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 XML Web service method formatting styles. For more details on XML Web service method formatting styles see Modifying the Overall SOAP BODY Formatting

    [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) {
    [Visual Basic]
    <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>
    

Modifying the Overall SOAP Body Formatting

WSDL defines two styles for how an XML Web service method, which it calls an operation, can be formatted within the Body element of a SOAP request or SOAP response: RPC and Document. In ASP.NET, both the Document and RPC formatting styles are supported. Document is the default.

The RPC style refers to formatting the Body element according to the SOAP specification for using SOAP for RPC, which is otherwise known as Section 7 of the SOAP specification. This style states that all parameters are encapsulated within a single element, named after the XML Web service method, and that each element within that element represents a parameter named after its respective parameter name. It also describes rules for how SOAP responses are formatted.

The Document style refers to formatting the Body element as a series of one or more message parts under the Body element. Exactly how the individual message parts are formed is determined by the Use and ParameterStyle properties of the SoapDocumentMethod attribute. The Use property determines whether parameters are formatted as Encoded or Literal. The ParameterStyle determines whether the parameters are encapsulated within a single message part beneath the Body element, or whether each parameter is an individual message part. For details on setting the ParameterStyle property, see Modifying Whether the Parameters are Encapsulated Within One XML Element.

To specify a Document formatting style

  • Apply a SoapDocumentMethod attribute to the method in the proxy class calling the pertinent XML Web service method.

    With the Document formatting style, XML Web services created using ASP.NET support 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) {
    [Visual Basic]
    <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
    

    As expected 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 XML Web service method. Since the first parameter to the DocumentWrappedLiteral XML Web service method is a class, and the Literal parameter formatting style was specified, an XSD schema is created for the address type.

    <s:elementname="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>
    

    Given the XSD schema 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 pertinent XML Web service method.

    With the RPC formatting style, ASP.NET supports just the Encoded parameter formatting style. Therefore, the following code example does not specify a Use property for the parameter formatting, because the SoapRpcMethod attribute does not have a Use property.

    [SoapRpcMethodAttribute("https://www.contoso.com/Rpc",
                            RequestNamespace="https://www.contoso.com",
                            ResponseNamespace="https://www.contoso.com")]
    public Address Rpc(Address address, bool useZipPlus4) {
    [Visual Basic]
    <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 comprising 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> 
    

Modifying Whether the Parameters are Encapsulated Within One XML Element

The parameters to an XML Web service method can be encapsulated within one XML element when they are mapped to XML elements residing within the Body element of the SOAP message. As you have seen, RPC always encapsulates the parameters within one element; however, you have a choice when using the Document formatting style. In the service description, the parameters are mapped to pieces of the SOAP message, called message parts. When the parameters are encapsulated within one XML element, the parameters are mapped to a single message part. Conversely when they are not, they can comprise multiple message parts.

To specify that parameters are encapsulated within one XML element

  • Apply a SoapDocumentMethod attribute to the method in the proxy class calling the pertinent XML Web service method, setting the ParameterStyle property to Wrapped.

    The following code example sets the ParameterStyle to Wrapped. It also sets the parameter formatting style to Literal.

    [SoapDocumentMethod("https://www.contoso.com/DocumentWrappedLiteral",
                        RequestNamespace="https://www.contoso.com",
                        ResponseNamespace="https://www.contoso.com", 
                        Use=SoapBindingUse.Literal, 
                        ParameterStyle=SoapParameterStyle.Wrapped)]
    public string DocumentWrappedLiteral(Address1 address, 
                                         bool useZipPlus4) {
    [Visual Basic]
    <SoapDocumentMethod("https://www.contoso.com/DocumentWrappedLiteral", _
                        RequestNamespace:="https://www.contoso.com", _
                        ResponseNamespace:="https://www.contoso.com", _
                        Use:=SoapBindingUse.Literal, _
                        ParameterStyle:=SoapParameterStyle.Wrapped)> _
    Public Function DocumentWrappedLiteral(ByVal address As Address1, _
                                 ByVal useZipPlus4 As Boolean) As String
    

    The XML portion of the SOAP request encapsulates the parameters in an element named by default after the XML Web service method.

    <?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>
    

    The XML portion of the SOAP response encapsulates the out parameters for the XML Web service method, including the result inside an element. The name of the encapsulating element, by default, is the name of the XML Web service method with Response appended to it.

    <?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>
        <DocumentWrappedLiteralResponse xmlns="https://www.contoso.com">
          <DocumentWrappedLiteralResult>string
          </DocumentWrappedLiteralResult>
        </DocumentWrappedLiteralResponse>
      </soap:Body>
    </soap:Envelope>
    

To specify that parameters directly follow the Body element

  • Apply a SoapDocumentMethod attribute to the method in the proxy class calling the pertinent XML Web service method, setting the ParameterStyle property to Bare.

    The following example, which was generated by Wsdl.exe, sets the ParameterStyle to Bare, along with setting the parameter formatting style to Literal. Since the namespace cannot be specified in an element encapsulating all parameters, the namespace must be specified individually for each parameter and return value. Applying an XmlElementAttribute to each parameter and to the return value, and setting the Namespace property, can do this.

    [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) {
    [Visual Basic]
    <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
    

    The XML elements that the parameters are mapped to within the SOAP request directly follow the Body element, with each specifying a namespace.

    <?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>
        <MyAddress xmlns="https://www.contoso.com">
          <Street>string</Street>
          <City>string</City>
          <Zip>string</Zip>
        </MyAddress>
        <useZipPlus4 xmlns="https://www.contoso.com">boolean</useZipPlus4>
      </soap:Body>
    </soap:Envelope>
    

    The out parameters, including the return value, are mapped to XML elements following the Body element within the SOAP response. The return value element name is the name of the XML Web service method with a Result suffix, by default.

    <?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>
        <DocumentBareLiteralResult xmlns="https://www.contoso.com">
           string</DocumentBareLiteralResult>
      </soap:Body>
    </soap:Envelope>
    

Customizing the SOAP Expected by an XML Web Service Method

If you need to change the SOAP expected by an XML Web service created using ASP.NET, the same mechanisms available to an XML Web service client created using ASP.NET are available. You can control the mapping of parameters to XML elements, the XML element representing the XML Web service method, and whether the mapped elements are encapsulated within an element. The same attributes can be used on a per-method basis — namely SoapDocumentMethod and SoapRpcMethod. In addition, you can set the default formatting settings at the XML Web service level by applying the corresponding SoapDocumentService and SoapRpcService attributes to the XML Web service. Applying a SoapDocumentService attribute to an XML Web service sets the default method formatting style for its XML Web service methods to Document. Likewise, SoapRpcService attribute sets the default to RPC.

To set the default method formatting style for an XML Web service

  • Apply either a SoapRpcService attribute or a SoapDocumentService attribute to the class implementing the XML Web service.

    The following code example sets the method formatting style to Document and the default parameter formatting to Literal, and specifies that the parameters must be encapsulated within a single element.

    <%@ WebService Language="C#" Class="SoapDocumentServiceSample" %>
     using System.Web.Services;
     using System.Web.Services.Protocols;
     using System.Web.Services.Description;
    
    [SoapDocumentService(Use=SoapBindingUse.Literal,
                         ParameterStyle=SoapParameterStyle.Wrapped)]
    [WebService(Namespace="https://www.contoso.com")]
    public class SoapDocumentServiceSample  
    {
        [ WebMethod ]
        public string UseDefaultEncoding(Address MyAddress, 
                                         bool useZipPlus4) 
        {
         return "Use the default encodings for this XML Web service.";
        }
    }
    [Visual Basic]
    <%@ WebService Language="VB" Class="SoapDocumentServiceSample" %>
    Imports System.Web.Services
    Imports System.Xml.Serialization
    Imports System.Web.Services.Protocols
    Imports System.Web.Services.Description
    
    < SoapDocumentService(Use := SoapBindingUse.Literal, _
                          ParameterStyle := SoapParameterStyle.Wrapped)> _
    Public Class SoapDocumentServiceSample
      < WebMethod > _
      Public Function UseDefaultEncoding(MyAddress as Address, _
                                         useZipPlus4 As Boolean) As String 
         Return "Use the default formattings for this XML Web service."
      End Function
    End Class 
    

    The XML portion of the SOAP request expected by the UseDefaultEncoding XML Web service method follows.

    <?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>
        <UseDefaultEncoding xmlns="https://www.contoso.com">
          <MyAddress>
            <Street>string</Street>
            <City>string</City>
            <Zip>string</Zip>
          </MyAddress>
          <useZipPlus4>boolean</useZipPlus4>
        </UseDefaultEncoding>
      </soap:Body>
    </soap:Envelope>
    

Customizing the SOAP Message With XML Serialization

Besides specifying the parameter formatting, the formatting style for the XML Web service method, and whether the parameters are encapsulated within one element or not, you can directly customize a SOAP message with XML serialization. You have already seen it done to some degree with the XmlElement attribute, but the System.Xml.Serialization namespace includes many attributes for manipulating XML. Given that SOAP uses XML to encode the data sent to and from an XML Web service, the attributes in the System.Xml.Serialization namespace are ideal for customizing the SOAP sent to and from an XML Web service. For more details, see System.Xml.Serialization.

To specify the name of the XML element representing a parameter

  • Apply an XmlElement attribute to the parameter, specifying the desired name for the element and, optionally, a namespace if the parameter formatting is set to Literal. If the parameter formatting is set to Encoded, apply a SoapElement attribute to the parameter.

    The following code example expects the element names representing the parameters to be MyAddressElement, MyZipElement, and ReturnValueElement. It also expects the element name representing the return value to be ReturnValueElement. The XML Web service method formatting in the sample is Document, which is the default for ASP.NET.

    <%@ WebService Language="C#" Class="SoapDocumentServiceSample" %>
     using System.Web.Services;
     using System.Web.Services.Protocols;
     using System.Xml.Serialization;
    
    [WebService(Namespace="https://www.contoso.com")] 
    public class SoapDocumentServiceSample  
    {
      [ WebMethod ]
      [ return: XmlElement("ReturnValueElement",IsNullable=false)]
      public Address ValidateAddress(
        [XmlElement("MyAddressElement")] Address MyAddress,
        [XmlElement("MyZipElement")] bool useZipPlus4) 
      {
        useZipPlus4 = true;    
        return new Address();
      }
    }
    [Visual Basic]
    <%@ WebService Language="VB" Class="SoapDocumentServiceSample" %>
     Imports System.Web.Services
     Imports System.Web.Services.Protocols
     Imports System.Xml.Serialization
    
    <WebService(Namespace := "https://www.contoso.com")> _
    Public Class SoapDocumentServiceSample
      < WebMethod > _
      Public Function ValidateAddress( _
           <XmlElement("MyAddressElement")> MyAddress As Address, _
           <XmlElement("MyZipElement")> useZipPlus4 As Boolean)  
           As <XmlElement("ReturnValueElement",IsNullable :=false)> _
           Address 
            useZipPlus4 = True 
         Return new Address()
      End Function
    End Class
    

    The XML Web service expects the following SOAP request. Notice the names of the elements match what is specified in the XmlElement attribute, as opposed to the parameter names.

    <?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>
        <ValidateAddress xmlns="http://tempuri.org/">
          <MyAddressElement>
            <Street>string</Street>
            <City>string</City>
            <Zip>string</Zip>
          </MyAddressElement>
          <MyZipElement>boolean</MyZipElement>
        </ValidateAddress>
      </soap:Body>
    </soap:Envelope>
    

See Also

Introducing XML Serialization | System.Xml.Serialization Namespace | Altering the SOAP Message Using SOAP Extensions | SoapDocumentMethodAttribute | SoapRpcMethodAttribute | SoapDocumentServiceAttribute | SoapRpcServiceAttribute | Building XML Web Services Using ASP.NET | Building XML Web Service Clients