How to: Handle SOAP Headers Required by an XML Web Service Client

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

Code Example

A client can require a Web service method to interpret the semantics of the SOAP header correctly and process it accordingly for the SOAP request to succeed. To do so, clients set the mustUnderstand attribute of the SOAP header to 1. For instance, the following SOAP request requires the SOAP request recipient to process the MyCustomSoapHeader SOAP header.

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/" >
  <soap:Header>
    <MyCustomSoapHeader soap:mustUnderstand="1" xmlns="https://www.contoso.com">
      <custom>Keith</custom>
    </MyCustomSoapHeader>
  </soap:Header>
  <soap:Body>
    <MyUnknownHeaders xmlns="https://www.contoso.com" />
  </soap:Body>
</soap:Envelope>

Whether the Web service defines the SOAP header determines how the Web service should handle SOAP headers required by the client. ASP.NET handles a lot of the work in the case where the Web service defines the SOAP header. In the procedure that follows, you can learn how to handle the two cases.

To handle SOAP headers not defined by the Web service, but required by a Web service client

1. Follow the steps for handling unknown SOAP headers from a Web service client, paying particular attention to the DidUnderstand property of the SOAP header.

   For SOAP headers not defined by the Web service, the initial value of DidUnderstand is false. If ASP.NET detects SOAP headers with their DidUnderstand property set to false after the Web service method returns, a SoapHeaderException is automatically thrown.

To handle SOAP headers required by a Web service client and defined by the Web service

1. Follow the steps for processing SOAP headers within a Web service created using ASP.NET within each Web service method.

   For SOAP headers defined by the Web service and processed in the Web service method that receives the SOAP header, ASP.NET assumes the Web service understands the SOAP header and sets the initial value of DidUnderstand to true.

Example

The following MyWebService Web service defines the MyHeader SOAP header and requires it to be sent with any calls to the MyWebMethod Web service method. Additionally, the MyWebMethod processes any unknown SOAP headers. For the SOAP headers MyWebMethod can process, DidUnderstand is set to true.

<%@ WebService Language="C#" Class="MyWebService" %>
using System.Web.Services;
using System.Web.Services.Protocols;

// Define a SOAP header by deriving from the SoapHeader base class.
public class MyHeader : SoapHeader {
    public string MyValue;
}
public class MyWebService {
    public MyHeader myHeader;

    // Receive all SOAP headers other than the MyHeader SOAP header.
    public SoapUnknownHeader[] unknownHeaders;
 
    [WebMethod]
    [SoapHeader("myHeader")]
    //Receive any SOAP headers other than MyHeader.
    [SoapHeader("unknownHeaders")]
    public string MyWebMethod() 
    {
       foreach (SoapUnknownHeader header in unknownHeaders) 
       {
         // Perform some processing on the header.
         if (header.Element.Name == "MyKnownHeader")
               header.DidUnderstand = true;
         else
                // For those headers that cannot be 
                // processed, set DidUnderstand to false.
                header.DidUnderstand = false;
       }
       return "Hello";
    }
}

<%@ WebService Language="VB" Class="MyWebService" %>
Imports System.Web.Services
Imports System.Web.Services.Protocols

' Define a SOAP header by deriving from the SoapHeader base class.
Public Class MyHeader : Inherits SoapHeader
    Public MyValue As String
End Class

Public Class MyWebService
    Public myHeader As MyHeader
    
    ' Receive all SOAP headers other than the MyHeader SOAP header.
    Public unknownHeaders() As SoapUnknownHeader    
    
    <WebMethod, _
     SoapHeader("myHeader"), _
     SoapHeader("unknownHeaders")> _
    Public Function MyWebMethod() As String
        'Receive any SOAP headers other than MyHeader.
        Dim header As SoapUnknownHeader        For Each header In unknownHeaders
            ' Perform some processing on the header.
            If header.Element.Name = "MyKnownHeader" Then
                header.DidUnderstand = True
            ' For those headers that cannot be 
            ' processed, set DidUnderstand to false.
            Else
                header.DidUnderstand = False
            End If
        Next header
        Return "Hello"
    End Function
End Class

Note

The DidUnderstand property is used by ASP.NET to communicate with the Web service method. It is not part of the SOAP specification; its value does not appear in any part of the SOAP request or SOAP response.

Note

If a Web service forwards a SOAP header, it is very important to follow the rules in the SOAP specification, especially those that pertain to the value of the Actor . For details, see the W3C Web site (http://www.w3.org/TR/SOAP/).

See Also

Reference

SoapHeader
SoapHeaderAttribute
SoapUnknownHeader
SoapHeaderException

Concepts

Building XML Web Service Clients

Other Resources

Using SOAP Headers
XML Web Services Using ASP.NET