Share via

How to: Customize SOAP Messages with XML Serialization

  • Article

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

The System.Web.Serialization namespace provides numerous attributes for controlling XML serialization that can be applied to the parameters and return values of Web service methods. This topic shows how to use the XmlElementAttribute attribute.

To specify the name of the XML element representing a parameter

  1. Apply an XmlElement attribute to the parameter, which specifies 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 that represent the parameters to be MyAddressElement, MyZipElement, and ReturnValueElement. It also expects the element name that represents the return value to be ReturnValueElement. The 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();
  }
}

    <%@ 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 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

Reference

System.Xml.Serialization Namespace
SoapDocumentMethodAttribute
SoapRpcMethodAttribute
SoapDocumentServiceAttribute
SoapRpcServiceAttribute

Concepts

SOAP Message Modification Using SOAP Extensions
Building XML Web Service Clients

Other Resources

Customizing SOAP Message Formatting
Introducing XML Serialization
XML Web Services Using ASP.NET