How to: Define and Process 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.

Code Example

Web services created using ASP.NET can define and manipulate SOAP headers. Defining a SOAP header is accomplished by defining a class representing the data in a particular SOAP header and deriving it from the SoapHeader class.

To define a class representing a SOAP header

Create a class deriving from the SoapHeader class with a name matching the root element for the SOAP header.
```
public class MyHeader : SoapHeader
```
```
Public Class MyHeader : Inherits SoapHeader
```

Add public fields or properties, matching the names and their respective data types for each element in the SOAP header.

For instance, given the following SOAP header, the class following it defines a class representing the SOAP header.

<soap:Header xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/">
  <MyHeader xmlns="https://www.contoso.com">
    <Created>dateTime</Expires>
    <Expires>long</Expires>
  </MyHeader>
</soap:Header>

public class MyHeader : SoapHeader 
{
   public DateTime Created;
   public long Expires;
}

Public Class MyHeader : Inherits SoapHeader 
   Public Created As DateTime
   Public Expires As Long
End Class

To process SOAP headers within a Web service

Add a public member to the class implementing the Web service of the type representing the SOAP header.

[WebService(Namespace="https://www.contoso.com")]
public class MyWebService 
{
    // Add a member variable of the type deriving from SoapHeader.
    public MyHeader timeStamp;

<WebService(Namespace:="https://www.contoso.com")> _
Public Class MyWebService
    ' Add a member variable of the type deriving from SoapHeader.
    Public TimeStamp As MyHeader

Apply a SoapHeader attribute to each Web service method that intends to process the SOAP header. Set the MemberName property of the SoapHeader attribute to the name of the member variable created in the first step.
```
    [WebMethod]
    [SoapHeader("timeStamp")]
    public void MyWebMethod()
```
```
    <WebMethod, SoapHeader("TimeStamp")> _ 
    Public Sub MyWebMethod()
```

Within each Web service method that the SoapHeader attribute is applied to, access the member variable created in the first step to process the data sent in the SOAP header.

    [WebMethod]
    [SoapHeader("myHeaderMemberVariable")]
    public string MyWebMethod() 
    {
        // Verify that the client sent the SOAP Header.
        if (timeStamp == null) timeStamp = new MyHeader();
        // Set the value of the SoapHeader returned to the client.
        timeStamp.Expires = 60000;
        timeStamp.Created = DateTime.UtcNow;

        return("Hello World!");
    }

    <WebMethod,SoapHeader("TimeStamp", _
                          Direction:=SoapHeaderDirection.InOut)> _ 
    Public Function MyWebMethod() As String
        ' Process the SoapHeader.
        If (TimeStamp Is Nothing) Then
            TimeStamp = New MyHeader
        End If
        TimeStamp.Expires = 60000
        TimeStamp.Created = DateTime.UtcNow

        Return "Hello World!"
    End Function

Example

The following code example demonstrates how to define and process a SOAP header in a Web service created using ASP.NET. The MyWebService Web service has a member variable named myHeaderMemberVariable, which is of a type deriving from SoapHeader (MyHeader) and set to the MemberName property of the SoapHeader attribute. In addition, a SoapHeader attribute is applied to the MyWebMethod Web service method specifying myHeaderMemberVariable. Within the MyWebMethod Web service method, myHeaderMemberVariable is accessed to get the value of the Username XML element of the SOAP header.

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

// Define a SOAP header by deriving from the SoapHeader class.
public class MyHeader : SoapHeader 
{
   public DateTime Created;
   public long Expires;
}

[WebService(Namespace="https://www.contoso.com")]
public class MyWebService 
{
    // Add a member variable of the type deriving from SoapHeader.
    public MyHeader myHeaderMemberVariable;
 
    // Apply a SoapHeader attribute.
    [WebMethod]
    [SoapHeader("myHeaderMemberVariable")]
    public void MyWebMethod() 
    {
        // Process the SoapHeader.
        if (myHeaderMemberVariable.Username == "admin")
        {
           // Do something interesting.
        }
    }
}

<%@ 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 Username As String
    Public Password As String
End Class

<WebService(Namespace:="https://www.contoso.com")> _
Public Class MyWebService 
    ' Add a member variable of the type deriving from SoapHeader.
    Public myHeaderMemberVariable As MyHeader
 
    ' Apply a SoapHeader attribute.
    <WebMethod, SoapHeader("myHeaderMemberVariable")> _
    Public Sub MyWebMethod()
        ' Process the SoapHeader.
        If (myHeaderMemberVariable.Username = "admin") Then
           ' Do something interesting.
        End If
    End Sub
End Class

In the previous example, if the SOAP request to the MyWebMethod has a MyHeader SOAP header with a UserName element set to Admin, additional code is executed. That is, the following SOAP request causes that code to execute.

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <MyHeader xmlns="https://www.contoso.com">
      <Created>dateTime</Created>
      <Expires>long</Expires>
    </MyHeader>
  </soap:Header>
  <soap:Body>
    <MyWebMethod xmlns="https://www.contoso.com" />
  </soap:Body>
</soap:Envelope>

How to: Define and Process SOAP Headers

To define a class representing a SOAP header

To process SOAP headers within a Web service

Example

See Also

Reference

Concepts

Other Resources

Additional resources