How to: Change a SOAP Header's Recipients

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

By default, SOAP headers are sent by a Web service client to a Web service method when a SoapHeader attribute is applied to a Web service method. However, a SOAP header can also be sent by the Web service method back to the Web service client. It can also be sent both ways. Setting the Direction property of a SoapHeader attribute applied to a Web service method controls the recipient of the SOAP header. The Direction property is of type SoapHeaderDirection, which has four values: In, Out, InOut, and Fault. These refer to the recipient (whether it is the Web service server), to the client, or both the Web service server and client, and whether the SOAP header is sent to the client when an exception is thrown by the Web service, respectively.

Note: Version 1.0 of the .NET Framework SDK does not support the Fault value.

To change the SOAP header recipient

1. Define the SOAP header.

   public class MyHeader : SoapHeader 
   {
       public string Username;
       public string Password;
   }
   

   Public Class MyHeader : Inherits SoapHeader 
       Public Username As String
       Public Password As String
   End Class
   

2. Add a member variable to the class implementing the Web service.

   [WebService(Namespace="https://www.contoso.com")]
   public class MyWebService : WebService
   {
       public MyHeader myOutHeader;
   

   <WebService(Namespace:="https://www.contoso.com")> _
   Public Class MyWebService : Inherits WebService
       Public myOutHeader As MyHeader
   

3. Apply a SoapHeader attribute to each Web service method that processes the SOAP header. Set the Direction property to each intended recipient, using the SoapHeaderDirection enumeration. The following example sets the Web service client as the recipient by setting Direction to SoapHeaderDirection.Out.

   
       [WebMethod]
       [SoapHeader("myOutHeader",Direction=SoapHeaderDirection.Out)]
   

       <WebMethod, _
        SoapHeader("myOutHeader",Direction:=SoapHeaderDirection.Out)>
   

4. Process or set the SOAP header, depending on the recipient. The following code example sets the values of the SOAP header, as the recipient is the Web service client.

         // Return the client's authenticated name.
         myOutHeader.Username = User.Identity.Name;
   

         ' Return the client's authenticated name.
         myOutHeader.Username = User.Identity.Name
   
   

Example

The following code example defines a MyHeader SOAP header that is sent from the Web service method to the client.

<%@ 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 Username;
    public string Password;
}

[WebService(Namespace="https://www.contoso.com")]
public class MyWebService : WebService
{
    public MyHeader myOutHeader;
 
    [WebMethod]
    [SoapHeader("myOutHeader",Direction=SoapHeaderDirection.Out)]
    public void MyOutHeaderMethod() 
    {
      // Return the client's authenticated name.
      myOutHeader.Username = User.Identity.Name;          
    }
}

<%@ 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 : Inherits WebService
    Public myOutHeader As MyHeader 
    
    <WebMethod, _
     SoapHeader("myOutHeader",Direction:=SoapHeaderDirection.Out)> _
    Public Sub MyOutHeaderMethod()
        ' Return the client's authenticated name.
        myOutHeader.Username = User.Identity.Name
    End Sub
End Class

See Also

Reference

SoapHeader
SoapHeaderAttribute
SoapUnknownHeader
SoapHeaderException

Concepts

Building XML Web Service Clients

Other Resources

Using SOAP Headers
XML Web Services Using ASP.NET