Compartir a través de

Utilizar encabezados SOAP

La comunicación con un método de servicio Web XML mediante SOAP sigue un formato estándar. Parte de este formato son los datos que se codifican en un documento XML. El documento XML consta de una etiqueta Envelope que, a su vez, consta de un elemento requerido Body y un elemento opcional Header. El elemento Body incluye los datos específicos del mensaje. El elemento opcional Header puede contener información adicional no relacionada directamente con el mensaje específico. Cada elemento secundario del elemento Header se denomina encabezado SOAP.

Aunque los encabezados SOAP pueden contener datos relacionados con el mensaje, dado que en la especificación de SOAP no se define estrictamente el contenido de un encabezado SOAP, suelen contener información procesada por la infraestructura de un servidor Web. A modo de ejemplo, un encabezado SOAP se puede utilizar para suministrar información de enrutamiento del mensaje SOAP.

Definir y procesar encabezados SOAP

Los servicios Web XML creados mediante ASP.NET pueden definir y manipular encabezados SOAP. Para definir un encabezado SOAP se define una clase que represente los datos de un encabezado SOAP determinado y se derive de la clase SoapHeader.

Para definir una clase que represente un encabezado SOAP

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

    public class MyHeader : SoapHeader
[Visual Basic]
Public Class MyHeader : Inherits SoapHeader

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

    Por ejemplo, a continuación del siguiente encabezado SOAP se define una clase que representa el encabezado SOAP.

    public class MyHeader : SoapHeader
{
   public DateTime Created;
   public long Expires;
} 
[Visual Basic]
Public Class MyHeader
  Inherits SoapHeader
    Public Created As DateTime
    Public Expires As Long
End Class

Para procesar encabezados SOAP en un servicio Web XML

  1. Agregue un miembro público a la clase que implementa el servicio Web XML 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;
[Visual Basic]
<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 XML que vaya a procesar el encabezado SOAP. Establezca el nombre de la variable miembro creada en el primer paso como valor de la propiedad MemberName del atributo SoapHeader.

    [WebMethod]
[SoapHeader("timeStamp")]
public void MyWebMethod()
[Visual Basic]
<WebMethod, SoapHeader("TimeStamp")> _ 
Public Sub MyWebMethod()

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

    [WebMethod]
[SoapHeader("timeStamp",            Direction=SoapHeaderDirection.InOut)]
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";
}
[Visual Basic]
<WebMethod,SoapHeader("TimeStamp", _                      Direction:=SoapHeaderDirection.InOut)> _ 
Public Function MyWebMethod() As String
   ' Verify that the client sent the SOAP Header. 
   If (TimeStamp Is Nothing) Then
      TimeStamp = New MyHeader
   End If

   ' Set the value of the SoapHeader returned
   ' to the client.
   TimeStamp.Expires = 60000
   TimeStamp.Created = DateTime.UtcNow

   Return "Hello World"
End Function

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

<%@ WebService Language="C#" Class="MyWebService" %>
using System;
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 : System.Web.Services.WebService
{
   // Add a member variable of the type deriving from SoapHeader.
   public MyHeader timeStamp;

   // Apply a SoapHeader attribute.
   [WebMethod]
   [SoapHeader("timeStamp", Direction=SoapHeaderDirection.InOut)]
   public string HelloWorld()
   {
      if (timeStamp == null)
         timeStamp = new MyHeader();
         
      timeStamp.Expires = 60000;
      timeStamp.Created = DateTime.UtcNow;
         
      return "Hello World";
   }
} 
[Visual Basic]
<%@ WebService Language="VB" Class="MyWebService" %>
Imports System
Imports System.Web.Services
Imports System.Web.Services.Protocols

' Define a SOAP header by deriving from the SoapHeader class.
Public Class MyHeader
    Inherits SoapHeader
    Public Created As DateTime
    Public Expires As Long
End Class

<WebService(Namespace:="https://www.contoso.com")> _
Public Class MyWebService
    Inherits System.Web.Services.WebService

    ' Add a member variable of the type deriving from SoapHeader.
    Public timeStamp As MyHeader

    ' Apply a SoapHeader attribute.
    <WebMethod(), _
     SoapHeader("timeStamp", Direction:=SoapHeaderDirection.InOut)> _
    Public Function HelloWorld() As String

        If (timeStamp Is Nothing) Then
            timeStamp = New MyHeader
        End If

        timeStamp.Expires = 60000
        timeStamp.Created = DateTime.UtcNow

        Return "Hello World"
    End Function
End Class
In the previous example, a SOAP response is returned to the client with the Expires element set to 60000 (number of milliseconds, so 1 minute) and the Created element to the current time in coordinated universal time.  That is, the following SOAP response is sent to the client.
<? 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</Username>
      <Expires>long</Password>
    </MyHeader>
  </soap:Header>
  <soap:Body>
    <HelloWorldResponse xmlns="https://www.contoso.com" />
  </soap:Body>
</soap:Envelope>

Crear un cliente que procese encabezados SOAP

Un cliente de servicios Web XML puede enviar y recibir encabezados SOAP cuando se comunica con un servicio Web XML. Si se utiliza la utilidad Wsdl.exe para generar una clase de proxy para un servicio Web XML que espera recibir o devuelve encabezados SOAP, la clase de proxy incluye información acerca de los encabezados SOAP. Específicamente, la clase de proxy tiene variables miembro que representan los encabezados SOAP correspondientes a los del servicio Web XML. La clase de proxy también tiene definiciones para las clases correspondientes que representan el encabezado SOAP. Por ejemplo, las clases de proxy generadas para el servicio Web XML anterior tendrán una variable miembro de tipo MyHeader y una definición para la clase MyHeader. Para obtener más información sobre cómo crear una clase de proxy, vea Crear un proxy de servicio Web XML.

Nota: si en el servicio Web XML se definen variables miembro que representan los encabezados SOAP de tipo SoapHeader o SoapUnknownHeader en lugar de una clase que se deriva de SoapHeader, una clase de proxy no tendrá información acerca de ese encabezado SOAP.

Para procesar encabezados SOAP en un cliente de servicios Web XML

  1. Cree una instancia nueva de la clase que representa el encabezado SOAP.

    Dim header As MyHeader = New MyHeader()
[C#]
MyHeader header = new MyHeader();

  2. Llene los valores del encabezado SOAP.

    header.Expires = 60000
header.Created = DateTime.UtcNow
[C#]
header.Expires = 60000;
header.Created = DateTime.UtcNow;

  3. Cree una instancia nueva de la clase de proxy.

    Dim proxy As MyWebService = New MyWebService()
[C#]
MyWebService proxy = new MyWebService();

  4. Asigne el objeto de encabezado SOAP a la variable miembro de la clase de proxy que representa el encabezado SOAP.

    proxy.MyHeaderValue = header
[C#]
proxy.MyHeaderValue = header;

  5. Llame al método en la clase de proxy que se comunica con el método de servicio Web XML.

    La parte de encabezado SOAP de la solicitud SOAP enviada al servicio Web XML incluirá el contenido de los datos almacenados en el objeto de encabezado SOAP.

    Dim results as String = proxy.MyWebMethod()
[C#]
string results = proxy.MyWebMethod();

En el ejemplo de código siguiente se demuestra cómo pasar un encabezado SOAP desde un cliente a un servicio Web XML.

<%@ Page Language="VB" %>

<asp:Label id="ReturnValue" runat="server" />
<script runat=server language=VB>

 Sub Page_Load(o As Object, e As EventArgs)

  Dim header As MyHeader = New MyHeader()  ' Populate the values of the SOAP header.   header.Expires = 60000   header.Created = DateTime.UtcNow

  ' Create a new instance of the proxy class.
  Dim proxy As MyWebService = New MyWebService()
  
  ' Add the MyHeader SOAP header to the SOAP request.  proxy.MyHeaderValue = header

  ' Call the method on the proxy class that communicates
  ' with your XML Web service method.
  Dim results as String = proxy.MyWebMethod()

  ' Display the results of the method in a label.
  ReturnValue.Text = results

 End Sub
</script>
[C#]
<%@ Page Language="C#" %>

<asp:Label id="ReturnValue" runat="server" />
<script runat=server language=c#>

 void Page_Load(Object o, EventArgs e)
 {

  MyHeader header = new MyHeader();  // Populate the values of the SOAP header.  header.Expires = 60000;  header.Created = DateTime.UtcNow;

  // Create a new instance of the proxy class.
  MyWebService proxy = new MyWebService();
  
  // Add the MyHeader SOAP header to the SOAP request.  proxy.MyHeaderValue = header;

  // Call the method on the proxy class that communicates 
  // with your XML Web service method.
  string results = proxy.MyWebMethod();

  // Display the results of the method in a label.
  ReturnValue.Text = results;
 }
</script>

Cambiar los destinatarios de encabezados SOAP

De forma predeterminada, un cliente de servicios Web XML envía encabezados SOAP a un método de servicio Web XML cuando se aplica un atributo SoapHeader a un método de servicio Web XML. Sin embargo, el método también puede enviar un encabezado SOAP al cliente de servicios Web XML. Asimismo, se puede enviar en ambas direcciones. El destinatario del encabezado SOAP se controla mediante el establecimiento de la propiedad Direction de un atributo SoapHeader aplicado a un método de servicio Web XML. La propiedad Direction es de tipo SoapHeaderDirection, que tiene cuatro valores: In, Out, InOut y Fault. Estos valores hacen referencia al destinatario (sea o no el servidor de servicios Web XML), cliente o servidor de servicios Web XML y cliente, y determinan si se envía o no el encabezado SOAP al cliente cuando el servicio Web XML inicia una excepción, respectivamente.

Nota: la versión 1.0 de .NET Framework SDK no admite el valor Fault.

Para cambiar el destinatario del encabezado SOAP

  1. Defina el encabezado SOAP.

    public class MyHeader : SoapHeader
{
   public DateTime Created;
   public long Expires;
} 
[Visual Basic]
Public Class MyHeader
  Inherits SoapHeader
    Public Created As DateTime
    Public Expires As Long
End Class

  2. Agregue una variable miembro a la clase que implementa el servicio Web XML.

    [WebService(Namespace="https://www.contoso.com")]
public class MyWebService : WebService
{
    public MyHeader myOutHeader;
[Visual Basic]
<WebService(Namespace:="https://www.contoso.com")> _
Public Class MyWebService  
  Inherits WebService
    Public myOutHeader As MyHeader

  3. Aplique un atributo SoapHeader a cada método de servicio Web XML que procese el encabezado SOAP. Establezca la propiedad Direction para cada uno de los destinatarios previstos, mediante la enumeración SoapHeaderDirection. En el ejemplo siguiente se establece Direction como SoapHeaderDirection.Out para especificar el cliente de servicios Web XML como destinatario.

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

  4. Procese o establezca el encabezado SOAP, dependiendo del destinatario. En el ejemplo de código siguiente se establecen los valores del encabezado SOAP, puesto que el destinatario es el cliente de servicios Web XML.

    // Set the Time the SOAP message expires.
myOutHeader.Expires = 60000;
myOutHeader.Created = DateTime.UtcNow;
[Visual Basic]
' Set the Time the SOAP message expires.
myOutHeader.Expires = 60000
myOutHeader.Created = DateTime.UtcNow

En el ejemplo de código siguiente se define un encabezado SOAP MyHeader que se envía desde el método de servicio Web XML al cliente.

<%@ WebService Language="C#" Class="MyWebService" %>
using System;
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 : WebService
{
    public MyHeader myOutHeader;
 
    [WebMethod]
    [SoapHeader("myOutHeader",Direction=SoapHeaderDirection.Out)]
    public void MyOutHeaderMethod() 
    {
      // Set the time the SOAP message expires.
      myOutHeader.Expires = 60000;
      myOutHeader.Created = DateTime.UtcNow;
    }
}
[Visual Basic]
<%@ WebService Language="VB" Class="MyWebService" %>
Imports System
Imports System.Web.Services
Imports System.Web.Services.Protocols

' Define a SOAP header by deriving from the SoapHeader class.
Public Class MyHeader
  Inherits SoapHeader
    Public Created As DateTime
    Public Expires As Long
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()
         ' Set the time the SOAP message expires.
         myOutHeader.Expires = 60000
         myOutHeader.Created = DateTime.UtcNow
    End Sub
End Class

Controlar encabezados SOAP desconocidos

Un cliente de servicios Web XML puede enviar a un método de servicio Web XML una solicitud SOAP con un encabezado SOAP cuya recepción no esté definida de forma explícita en el servicio Web XML. En este caso, es importante determinar si la semántica del encabezado SOAP se entiende y se procesa, dado que en la especificación SOAP se indica que se inicia una excepción cuando los encabezados SOAP tienen un atributo mustUnderstand establecido a true. Para obtener más información sobre cómo controlar los encabezados SOAP requeridos por un cliente, vea Controlar encabezados SOAP requeridos por un cliente de servicios Web XML.

Para controlar encabezados SOAP desconocidos desde un cliente de servicios Web XML

  1. Agregue una variable miembro a la clase que implementa el servicio Web XML con un tipo SoapUnknownHeader o SoapHeader, o una matriz de uno de ellos, para controlar varios encabezados SOAP desconocidos.

    La declaración del tipo como una matriz o una única instancia de SoapUnknownHeader tiene la ventaja adicional de que SoapUnknownHeader tiene una propiedad Element. La propiedad Element es de tipo XmlElement y representa el documento XML para el elemento Header de la solicitud SOAP o la respuesta SOAP. En consecuencia, un método de servicio Web XML puede determinar el nombre del encabezado SOAP, junto con los datos pasados en el encabezado SOAP, mediante la consulta de la propiedad Element.

    public class MyWebService {
    public SoapUnknownHeader[] unknownHeaders;
[Visual Basic]
Public Class MyWebService
    Public unknownHeaders() As SoapUnknownHeader

  2. Aplique un atributo SoapHeader a cada método de servicio Web XML que vaya a procesar los encabezados SOAP desconocidos.

        [WebMethod]
    [SoapHeader("unknownHeaders")]
    public string MyWebMethod()
[Visual Basic]
    <WebMethod, _
     SoapHeader("unknownHeaders") > _
    Public Function MyWebMethod() As String

  3. Agregue código para determinar si puede procesar encabezados SOAP desconocidos.

    Si la variable miembro es de tipo SoapUnknownHeader, un método de servicio Web XML puede determinar el nombre del encabezado SOAP, junto con los datos pasados en él, mediante la consulta de la propiedad Element. La propiedad Name de la propiedad Element identifica el nombre del encabezado SOAP.

           foreach (SoapUnknownHeader header in unknownHeaders) 
       {
         // Check to see if this a known header.
         if (header.Element.Name == "MyKnownHeader")
[Visual Basic]
       Dim header As SoapUnknownHeader       
       For Each header In unknownHeaders
         ' Check to see if this is a known header.
         If (header.Element.Name = "MyKnownHeader") Then

  4. Establezca a true el valor de la propiedad DidUnderstand de la variable miembro que representa el encabezado SOAP desconocido si se conoce la forma de procesar un encabezado SOAP determinado.

    Si un método de servicio Web XML procesa un encabezado SOAP desconocido y no establece en true la propiedad DidUnderstand, se puede iniciar una excepción SoapHeaderException. Para obtener más información, vea Controlar encabezados SOAP requeridos por un cliente de servicios Web XML

             // 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;
         }
[Visual Basic]
         ' 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

    Nota   Los servicios Web XML creados mediante ASP.NET utilizan la propiedad DidUnderstand para comunicarse con el método de servicio Web XML. Ésta no forma parte de la especificación de SOAP. Su valor no aparece en ninguna parte de la solicitud SOAP o la respuesta SOAP.

    Nota   Cuando un cliente de servicios Web XML crea una clase de proxy mediante la herramienta Lenguaje de descripción de servicios Web (Wsdl.exe) y en un servicio Web XML se define la variable miembro que representa un encabezado SOAP con el tipo SoapUnknownHeader, no se agrega a la clase de proxy ninguna referencia a dicho encabezado SOAP. Si un cliente de servicios Web XML decide agregar ese encabezado SOAP a la solicitud SOAP, se debe modificar la clase de proxy para agregar una variable miembro y aplicar un atributo SoapHeader al método que realiza la llamada al método de servicio Web XML pertinente.

Controlar encabezados SOAP requeridos por un cliente de servicios Web XML

Para que la solicitud SOAP tenga éxito, un cliente puede requerir que un método de servicio Web XML interprete correctamente la semántica del encabezado SOAP y la procese como corresponda. Para que sea así, en los clientes se establece en 1 el atributo mustUnderstand del encabezado SOAP. Por ejemplo, en la siguiente solicitud SOAP se requiere que su destinatario procese el encabezado SOAP MyCustomSoapHeader.

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/" >
  <soap:Header>
    <MyCustomSoapHeader soap:mustUnderstand="1" xmlns="https://www.contoso.com">
      <custom>Keith</custom>
    </MyCustomSoapHeader>
  </soap:Header>
  <soap:Body>
    <MyUnknownHeaders xmlns="https://www.contoso.com" />
  </soap:Body>
</soap:Envelope>

La definición o no del encabezado SOAP en el servicio Web XML determina la forma en que el servicio Web XML debe controlar los encabezados SOAP requeridos por el cliente. ASP.NET se ocupa de gran parte del trabajo cuando el encabezado SOAP está definido en el servicio Web XML. En el procedimiento siguiente se explica cómo controlar los dos casos.

Para controlar encabezados SOAP no definidos en el servicio Web XML pero requeridos por un cliente de servicios Web XML

  • Siga los pasos para controlar encabezados SOAP desconocidos desde un cliente de servicios Web XML y preste especial atención a la propiedad DidUnderstand del encabezado SOAP.

    Para los encabezados SOAP que no están definidos en el servicio Web XML, el valor inicial de DidUnderstand es false. Si ASP.NET detecta encabezados SOAP con la propiedad DidUnderstand establecida a false después de que vuelva el método de servicio Web XML, se inicia automáticamente una excepción SoapHeaderException.

Para controlar encabezados SOAP requeridos por un cliente de servicios Web XML y definidos en el servicio Web XML

  • Siga los pasos para procesar encabezados SOAP en un servicio Web XML creado mediante ASP.NET en cada método de servicio Web XML.

    Para los encabezados SOAP definidos en el servicio Web XML y procesados en el método de servicio Web XML que recibe el encabezado SOAP, ASP.NET supone que el servicio Web XML entiende el encabezado SOAP y establece el valor inicial de DidUnderstand a true.

En el servicio Web MyWebService del ejemplo siguiente se define el encabezado SOAP MyHeader y se requiere que éste se envíe en todas las llamadas al método de servicios Web XML MyWebMethod. Además, el método MyWebMethod procesa los encabezados SOAP desconocidos. Para los encabezados SOAP que puede procesar MyWebMethod, la propiedad DidUnderstand se establece a true.

<%@ 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 string MyValue;
}
public class MyWebService {
    public MyHeader myHeader;

    // Receive all SOAP headers other than the MyHeader SOAP header.
    public SoapUnknownHeader[] unknownHeaders;
 
    [WebMethod]
    [SoapHeader("myHeader")]
    //Receive any SOAP headers other than MyHeader.
    [SoapHeader("unknownHeaders")]
    public string MyWebMethod() 
    {
       foreach (SoapUnknownHeader header in unknownHeaders) 
       {
         // Perform some processing on the header.
         if (header.Element.Name == "MyKnownHeader")
               header.DidUnderstand = true;
         else
                // For those headers that cannot be 
                // processed, set DidUnderstand to false.
                header.DidUnderstand = false;
       }
       return "Hello";
    }
}
[Visual Basic]
<%@ WebService Language="VB" Class="MyWebService" %>
Imports System.Web.Services
Imports System.Web.Services.Protocols

' Define a SOAP header by deriving from the SoapHeader class.
Public Class MyHeader : Inherits SoapHeader
    Public MyValue As String
End Class

Public Class MyWebService
    Public myHeader As MyHeader
    
    ' Receive all SOAP headers other than the MyHeader SOAP header.
    Public unknownHeaders() As SoapUnknownHeader    
    
    <WebMethod, _
     SoapHeader("myHeader"), _
     SoapHeader("unknownHeaders")> _
    Public Function MyWebMethod() As String
        'Receive any SOAP headers other than MyHeader.
        Dim header As SoapUnknownHeader        For Each header In unknownHeaders
            ' Perform some processing on the header.
            If header.Element.Name = "MyKnownHeader" Then
                header.DidUnderstand = True
            ' For those headers that cannot be 
            ' processed, set DidUnderstand to false.
            Else
                header.DidUnderstand = False
            End If
        Next header
        Return "Hello"
    End Function
End Class

Nota   ASP.NET utiliza la propiedad DidUnderstand para comunicarse con el método de servicio Web XML. Ésta no forma parte de la especificación SOAP; su valor no aparece en ninguna parte de la solicitud SOAP o la respuesta SOAP.

Si un servicio Web XML reenvía un encabezado SOAP, es muy importante seguir las reglas de la especificación SOAP, especialmente las referentes al valor de Actor. Para obtener más información, visite el sitio Web de W3C (World Wide Web Consortium), http://www.w3c.org/TR/SOAP/.

Controlar errores que se producen durante el procesamiento de un encabezado SOAP

Cuando un servicio Web XML detecta un error específico del procesamiento de un encabezado, se debe iniciar una excepción SoapHeaderException. El uso de esta clase de excepción permite que los servicios Web XML apliquen el formato correcto a la respuesta. Si el cliente se crea mediante .NET Framework, recibirá la excepción SoapHeaderException con su contenido, incluida la propiedad InnerException, colocada en la propiedad Message. La propiedad InnerException de la excepción SoapHeaderException detectada por el cliente será null. Éste es un modelo de programación admitido en .NET Framework, puesto que la excepción se envía a través de la red en un elemento XML <Fault> de SOAP, como se indica en la especificación de SOAP. Para obtener más información acerca de las excepciones, vea Controlar e iniciar excepciones en servicios Web XML.

En el ejemplo de código siguiente se inicia una excepción SoapHeaderException si un cliente realiza una solicitud SOAP al método de servicio Web XML MyWebMethod con el valor de la propiedad Username establecido a guest.

<%@ 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 DateTime Expires;
  public DateTime Received;
} 

[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() 
    {
       if (timeStamp == null)
          timeStamp = new MyHeader();
       else
       {
          // Check whether the SOAP message is expired.
          if ((timeStamp.Expires.CompareTo(DateTime.UtcNow)) <= 0)
          {
             // The SOAP message is expired, so throw a SOAP header
             // exception indicating that.
             SoapHeaderException se = new SoapHeaderException(
               "SOAP message expired before reaching this node.",
               SoapException.ClientFaultCode, 
               this.Context.Request.Url.ToString());
             throw se;
          }
       }
    }
}
[Visual Basic]
<%@ WebService Language="VB" Class="MyWebService" %>
Imports System.Web.Services
Imports System.Web.Services.Protocols

' Define a SOAP header by deriving from the SoapHeader class.
Public Class MyHeader 
  Inherits SoapHeader
    Public Created As DateTime
    Public Expires As DateTime
    Public Received As DateTime
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()
       If (TimeStamp Is Nothing) Then
          TimeStamp = New MyHeader
       Else
           ' Check whether the SOAP message is expired.
           If ((TimeStamp.Expires.CompareTo(DateTime.UtcNow)) <= 0) Then
             ' The SOAP message is expired, so throw a SOAP header
             ' exception indicating that.
             Dim se As New SoapHeaderException( _
                "SOAP message expired before reaching this node.", _
                SoapException.ClientFaultCode, _
                Me.Context.Request.Url.ToString())
             Throw se    
           End If
       End If
    End Sub
End Class

Nota: .NET Framework 1.0 incluye la propiedad SoapHeaderAttribute.Required que cuando se establece en true habilita un servicio Web XML que requiere que un cliente envíe un encabezado SOAP específico. ASP.NET indica que se requiere un encabezado SOAP en un documento WSDL generado si establece en "true" el atributo wsdl:required del elemento soap:header. Los clientes de .NET Framework del servicio Web XML creado a partir del documento WSDL reciben una excepción SoapHeaderException si no envían el encabezado SOAP especificado, y los otros clientes reciben un error de SOAP. Para interactuar con otras implementaciones SOAP, esta funcionalidad se ha quitado de las versiones posteriores.

La propiedad Required está obsoleta en la versión 1.1, y la herramienta Lenguaje de descripción de servicios Web (Wsdl.exe) no tiene en cuenta el atributo wsdl:required del elemento soap:header en un documento WSDL. Como ya no se requiere un encabezado SOAP, un servicio Web XML debe comprobar que el campo o a la propiedad que representa el encabezado SOAP no es de tipo null, antes de obtener acceso a él.

Vea también

SoapHeader | SoapHeaderAttribute | SoapHeaderException | SoapUnknownHeader | Generar servicios Web XML mediante ASP. NET | Generar clientes de servicios Web XML

  • Last updated on