Share via


How to: Define and Process SOAP Headers

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

  1. 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
    
  2. 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

  1. 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
    
  2. 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()
    
  3. 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>

See Also

Reference

SoapHeader
SoapHeaderAttribute
SoapUnknownHeader
SoapHeaderException

Concepts

Building XML Web Service Clients

Other Resources

Using SOAP Headers
XML Web Services Using ASP.NET