Cómo: Definir y procesar encabezados SOAP

Este tema es específico de una tecnología heredada. Ahora, los servicios Web XML y los clientes de servicios Web XML deben crearse con Windows Communication Foundation.

Ejemplo de código

Los servicios Web creados con ASP.NET pueden definir y manipular los encabezados SOAP. Definir un encabezado SOAP se logra definiendo una clase que representa los datos en un encabezado SOAP determinado y derivándolo de la clase SoapHeader.

Para definir una clase que representa un encabezado SOAP

1. Cree una clase que deriva de la clase SoapHeader con un nombre que coincida con el elemento raíz para el encabezado SOAP.

   public class MyHeader : SoapHeader
   

   Public Class MyHeader : Inherits SoapHeader
   

2. Agregue campos públicos o propiedades, haciendo que coincidan los nombres y sus tipos de datos respectivos en cada elemento del encabezado SOAP.

   Por ejemplo, determinado el encabezado SOAP siguiente, la clase que lo sigue define una clase que representa el encabezado SOAP.

   <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
   

Para procesar los encabezados SOAP dentro de un Servicio Web

1. Agregue un miembro público a la clase que implementa el servicio Web del tipo que representa el encabezado SOAP.

   [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. Aplique un atributo SoapHeader a cada método de servicio Web que pretenda procesar el encabezado SOAP. Establezca la propiedad MemberName del atributo SoapHeader en el nombre de la variable miembro creada en el primer paso.

       [WebMethod]
       [SoapHeader("timeStamp")]
       public void MyWebMethod()
   

       <WebMethod, SoapHeader("TimeStamp")> _ 
       Public Sub MyWebMethod()
   

3. Dentro de cada método de servicio Web al que se aplica el atributo SoapHeader, tenga acceso a la variable miembro creada en el primer paso para procesar los datos enviados en el encabezado SOAP.

       [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
   

Ejemplo

El ejemplo de código siguiente muestra cómo definir y procesar un encabezado SOAP en un servicio Web creado con ASP.NET. El servicio Web MyWebService tiene una variable miembro denominada myHeaderMemberVariable, que es de un tipo que deriva de SoapHeader (MyHeader) y se encuentra establecida en la propiedad MemberName del atributo SoapHeader. Además, un atributo SoapHeader se aplica al método de servicio Web MyWebMethod que especifica myHeaderMemberVariable. Dentro del método de servicio Web myHeaderMemberVariable se accede a Username para obtener el valor del elemento XML MyWebMethoddel encabezado SOAP.

<%@ 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

En el ejemplo anterior, si la solicitud SOAP a MyWebMethod tiene un encabezado SOAP MyHeader con un elemento UserName establecido en Admin, se ejecuta código adicional. Es decir, la siguiente solicitud SOAP produce que ese código se ejecute.

<?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>

Vea también

Referencia

SoapHeader
SoapHeaderAttribute
SoapUnknownHeader
SoapHeaderException

Conceptos

Generar clientes de servicios web XML

Otros recursos

Usar encabezados SOAP
Servicios web XML con ASP.NET