How to: Handle Unknown SOAP Headers

Article
02/13/2011

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

A Web service client can send a SOAP request with a SOAP header to a Web service method that the Web service was expecting, but might not have explicitly defined. In this case, it is important to determine whether the semantics of the SOAP header are understood and processed, as the SOAP specification states that an exception is thrown when SOAP headers have a mustUnderstand attribute set to true. For details on handling SOAP headers required by a client, see Handling SOAP Headers Required by an XML Web Service Client.

To handle unknown SOAP headers from a Web service client

Add a member variable to the class that implements the Web service with a type of SoapUnknownHeader or SoapHeader, or an array of either, to handle multiple unknown SOAP headers.

Declaring the type as either an array or a single instance of SoapUnknownHeader has the added benefit that SoapUnknownHeader has an Element property. The Element property is of type XmlElement and represents the XML document for the Header element of the SOAP request or SOAP response. Thus, a Web service method can determine the name of the SOAP header, along with the data passed by the SOAP header, by interrogating the Element property.
```
public class MyWebService {
    public SoapUnknownHeader[] unknownHeaders;
```
```
Public Class MyWebService
    Public unknownHeaders() As SoapUnknownHeader
```

Apply a SoapHeader attribute to each Web service method that intends to process each unknown SOAP header.


    [WebMethod]
    [SoapHeader("unknownHeaders")]
    public string MyWebMethod()

    <WebMethod, _
     SoapHeader("unknownHeaders") > _
    Public Function MyWebMethod() As String

Add code to determine whether you can process any unknown SOAP headers.

If the member variable is of type SoapUnknownHeader, a Web service method can determine the name of the SOAP header, along with the data passed by the SOAP header, by interrogating the Element property. The Name property of Element property identifies the name of the SOAP header.


       foreach (SoapUnknownHeader header in unknownHeaders) 
       {
         // Check to see if this a known header.
         if (header.Element.Name == "MyKnownHeader")

       Dim header As SoapUnknownHeader       
       For Each header In unknownHeaders
         ' Check to see if this is a known header.
         If (header.Element.Name = "MyKnownHeader") Then

Set the DidUnderstand property of the member variable that represents the unknown SOAP header to true if it is known how to process a particular SOAP header.

If a Web service method does process an unknown SOAP header and does not set the DidUnderstand property to true, a SoapHeaderException can be thrown. For more details, see Handling SOAP Headers Required by an XML Web Service Client
```
         // Check to see if this is a known header.
         if (header.Element.Name == "MyKnownHeader")
               header.DidUnderstand = true;
         else
             // For those headers that cannot be 
             // processed, set DidUnderstand to false.
             header.DidUnderstand = false;
         }
```
```
         ' Check to see if this a known header.
         If (header.Element.Name = "MyKnownHeader") Then
               header.DidUnderstand = True
         Else
             ' For those headers that cannot be 
             ' processed, set DidUnderstand to false.
             header.DidUnderstand = False
         End If
```
Note

The DidUnderstand property is used by Web services created using 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

When a Web service client builds a proxy class using the Web Services Description Language Tool (Wsdl.exe) and a Web service defines the member variable that represents a SOAP header using the SoapUnknownHeader type, no reference to that SOAP header is added to the proxy class. If a Web service client decides to add that SOAP header to the SOAP request, they must modify the proxy class by adding a member variable and applying a SoapHeader attribute to the method making the call to the applicable Web service method.

How to: Handle Unknown SOAP Headers

To handle unknown SOAP headers from a Web service client

See Also

Reference

Concepts

Other Resources

Additional resources