Partager via

Utilisation d'en-têtes SOAP

  • Article

La communication avec une méthode de service Web XML créée à l'aide de SOAP respecte un format standard. Une partie de ce format est constituée des données encodées dans un document XML. Le document XML consiste en une balise Envelope racine qui est elle-même constituée d'un élément Body obligatoire et d'un élément Header optionnel. L'élément Body comprend les données spécifiques au message. L'élément Header optionnel peut contenir des informations supplémentaires qui ne sont pas directement en relation avec le message particulier. Chaque élément enfant de l'élément Header est appelé un en-tête SOAP.

Bien que les en-têtes SOAP puissent contenir des données relatives au message puisque la spécification SOAP n'en définit pas strictement le contenu, ils contiennent généralement les informations traitées par l'infrastructure dans un serveur Web. Un en-tête SOAP peut par exemple être utilisé pour fournir des informations de routage du message SOAP.

Définition et traitement des en-têtes SOAP

Les services Web XML créés à l'aide d'ASP.NET peuvent définir et manipuler les en-têtes SOAP. La définition d'un en-tête SOAP nécessite de définir une classe représentant les données d'un en-tête SOAP particulier et de la dériver de la classe SoapHeader.

Pour définir une classe représentant un en-tête SOAP

  1. Créez une classe dérivant de la classe SoapHeader avec un nom correspondant à l'élément racine de l'en-tête SOAP.

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

  2. Ajoutez des propriétés ou des champs publics, correspondant aux noms et à leurs types de données respectifs pour chaque élément de l'en-tête SOAP.

    Supposons par exemple l'en-tête SOAP ci-après, la classe qui le suit définit une classe représentant l'en-tête 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

Pour traiter des en-têtes SOAP dans un service Web XML

  1. Ajoutez un membre public à la classe implémentant le service Web XML du type représentant l'en-tête 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. Appliquez un attribut SoapHeader à chaque méthode de service Web XML destinée à traiter l'en-tête SOAP. Affectez à la propriété MemberName de l'attribut SoapHeader le nom de la variable de membre créée à la première étape.

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

  3. Dans chaque méthode de service Web XML à laquelle l'attribut SoapHeader est appliqué, accédez à la variable de membre créée à la première étape pour traiter les données envoyées dans l'en-tête 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

L'exemple de code suivant montre comment définir et traiter un en-tête SOAP dans un service Web XML créé à l'aide de ASP.NET. Le service Web XML MyWebService a une variable de membre nommée timeStamp, qui est d'un type dérivant de SoapHeader (MyHeader) et affectée à la propriété MemberName de l'attribut SoapHeader. De plus, un attribut SoapHeader est appliqué à la méthode de service Web XML MyWebMethod spécifiant myHeaderMemberVariable. Dans la méthode de service Web XML MyWebMethod, myHeaderMemberVariable est accessible pour définir la valeur des éléments XML Created et Expires de l'en-tête 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

Dans l'exemple précédent, une réponse SOAP est retournée au client avec la valeur 60 000 (nombre de millisecondes, soit 1 minute) affectée à l'élément Expires et l'heure actuelle en temps universel affectée à l'élément Created. En d'autres termes, la réponse SOAP suivante est envoyée au 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</Created>
      <Expires>long</Expires>
    </MyHeader>
  </soap:Header>
  <soap:Body>
    <MyWebMethod xmlns="https://www.contoso.com" />
  </soap:Body>
</soap:Envelope>

Création d'un client qui traite des en-têtes SOAP

Un client de service Web XML peut envoyer et recevoir des en-têtes SOAP lorsqu'il communique avec un service Web XML. Lorsqu'une classe proxy est générée pour un service Web XML attendant ou retournant des en-têtes SOAP à l'aide de l'utilitaire Wsdl.exe, elle inclut les informations concernant les en-têtes SOAP. En fait, la classe proxy a des variables de membre représentant les en-têtes SOAP qui sont en corrélation avec celles trouvées dans le service Web XML. La classe proxy a aussi des définitions des classes correspondantes représentant l'en-tête SOAP. Par exemple, les classes proxy générées pour le service Web XML précédent auront une variable de membre de type MyHeader et une définition pour la classe MyHeader. Pour plus d'informations sur la création d'une classe proxy, consultez Création d'un proxy de service Web XML.

Remarque : Si le service Web XML définit les variables de membre représentant les en-têtes SOAP de type SoapHeader ou SoapUnknownHeader au lieu d'une classe dérivant de SoapHeader, une classe proxy n'aura pas d'information concernant l'en-tête SOAP.

Pour traiter des en-têtes SOAP dans un client de service Web XML

  1. Créez une nouvelle instance de la classe représentant l'en-tête SOAP.

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

  2. Remplissez les valeurs pour l'en-tête SOAP.

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

  3. Créez une nouvelle instance de la classe proxy.

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

  4. Assignez l'objet d'en-tête SOAP à la variable de membre de la classe proxy représentant l'en-tête.

    proxy.MyHeaderValue = mySoapHeader
[C#]
proxy.MyHeaderValue = mySoapHeader

  5. Appelez la méthode sur la classe proxy qui communique avec la méthode de service Web XML.

    La partie en-tête SOAP de la demande SOAP envoyée au service Web XML inclura le contenu des données stockées dans l'objet d'en-tête SOAP.

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

L'exemple de code suivant illustre comment passer un en-tête SOAP d'un client à un service 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>

Modification des destinataires des en-têtes SOAP

Par défaut, les en-têtes SOAP sont envoyés par un client de service Web XML à une méthode de service Web XML lorsqu'un attribut SoapHeader est appliqué à la méthode. Un en-tête SOAP peut néanmoins être également renvoyé au client de service Web XML par la méthode du service. Il peut aussi être envoyé dans les deux sens. La définition de la propriété Direction d'un attribut SoapHeader appliquée à une méthode de service Web XML contrôle le destinataire de l'en-tête SOAP. La propriété Direction est de type SoapHeaderDirection, qui a quatre valeurs : In, Out, InOut et Fault. Ces valeurs se réfèrent respectivement au destinataire (qu'il s'agisse du serveur de service Web XML ou non), au client, au serveur et client de service Web XML ou au fait que l'en-tête SOAP est envoyé au client lorsqu'une exception est levée par le service Web XML.

Remarque : la version 1.0 du Kit de développement .NET Framework SDK ne prend pas en charge la valeur Fault.

Pour modifier le destinataire de l'en-tête SOAP

  1. Définissez l'en-tête 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. Ajoutez une variable de membre à la classe implémentant le service 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. Appliquez un attribut SoapHeader à chaque méthode de service Web XML qui traite l'en-tête SOAP. Affectez chaque destinataire prévu à la propriété Direction avec l'énumération SoapHeaderDirection. L'exemple suivant définit le client de service Web XML comme destinataire en affectant SoapHeaderDirection.Out à Direction.

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

  4. Traitez ou définissez l'en-tête SOAP, en fonction du destinataire. L'exemple de code suivant définit les valeurs de l'en-tête SOAP, puisque le destinataire est le client de service 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

L'exemple de code suivant définit un en-tête SOAP MyHeader envoyé au client à partir de la méthode de service Web XML.

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

Gestion d'en-têtes SOAP inconnus

Un client de service Web XML peut envoyer une demande SOAP avec un en-tête SOAP à une méthode de service Web XML que le service Web XML attendait sans l'avoir explicitement défini. Dans ce cas, il est important de déterminer si la sémantique de l'en-tête SOAP est comprise et traitée, puisque la spécification SOAP déclare qu'une exception est levée lorsque les en-têtes SOAP ont un attribut mustUnderstand ayant la valeur true. Pour plus d'informations sur la gestion des en-têtes SOAP requis par un client, consultez Gestion des en-têtes SOAP requis par un client de service Web XML.

Pour gérer des en-têtes SOAP inconnus à partir d'un client de service Web XML

  1. Ajoutez une variable de membre à la classe implémentant le service Web XML avec un type de SoapUnknownHeader ou SoapHeader ou un tableau de l'un d'eux, pour gérer plusieurs en-têtes SOAP inconnus.

    La déclaration du type comme un tableau ou une instance unique de SoapUnknownHeader a l'avantage supplémentaire que SoapUnknownHeader a une propriété Element. La propriété Element est de type XmlElement et représente le document XML pour l'élément Header de la demande ou la réponse SOAP. Ainsi, une méthode de service Web XML peut déterminer le nom de l'en-tête SOAP ainsi que les données passées par l'en-tête, en interrogeant la propriété Element.

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

  2. Appliquez un attribut SoapHeader à chaque méthode de service Web XML destinée à traiter chaque en-tête SOAP inconnu.

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

  3. Ajoutez du code pour déterminer si vous pouvez traiter les en-têtes SOAP inconnus.

    Si la variable de membre est de type SoapUnknownHeader, une méthode de service Web XML peut déterminer le nom de l'en-tête SOAP ainsi que les données passées par l'en-tête, en interrogeant la propriété Element. La propriété Name de la propriété Element identifie le nom de l'en-tête 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. Affectez true à la propriété DidUnderstand de la variable de membre représentant l'en-tête SOAP inconnu si le traitement d'un en-tête SOAP particulier est connu.

    Si une méthode de service Web XML ne traite pas un en-tête SOAP inconnu et n'affecte pas true à la propriété DidUnderstand, SoapHeaderException peut être levé. Pour plus d'informations, consultez Gestion des en-têtes SOAP requis par un client de service 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

    Remarque   La propriété DidUnderstand est utilisée par les services Web XML créés à l'aide d'ASP.NET pour communiquer avec la méthode de service. Elle ne fait pas partie de la spécification SOAP. Sa valeur n'apparaît dans aucune partie de la demande ni de la réponse SOAP.

    Remarque   Lorsqu'un client de service Web XML crée une classe proxy avec l'outil Web Services Description Language Tool (Wsdl.exe) et qu'un service Web XML définit la variable de membre représentant un en-tête SOAP avec le type SoapUnknownHeader, aucune référence à cet en-tête n'est ajoutée à la classe proxy. Si un client de service Web XML décide d'ajouter cet en-tête à la demande SOAP, il doit modifier la classe proxy en ajoutant une variable de membre et en appliquant un attribut SoapHeader à la méthode appelant la méthode de service Web XML pertinente.

Gestion des en-têtes SOAP requis par un client de service Web XML

Un client peut exiger qu'une méthode de service Web XML interprète correctement la sémantique de l'en-tête SOAP et la traite en conséquence pour que la demande SOAP aboutisse. Pour ce faire, les clients définissent l'attribut mustUnderstand de l'en-tête SOAP à 1. Par exemple, la demande SOAP suivante demande à son destinataire de traiter l'en-tête 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 définition ou non de l'en-tête SOAP par le service Web XML détermine la façon dont le service doit gérer les en-têtes requis par le client. ASP.NET gère une grande partie du travail dans le cas où le service Web XML définit l'en-tête SOAP. Dans la procédure qui suit, vous pouvez apprendre comment gérer les deux cas.

Pour gérer les en-têtes SOAP non définis par le service Web XML mais requis par un client de service Web XML

  • Procédez comme pour gérer les en-têtes SOAP inconnus à partir d'un client de service Web XML en faisant particulièrement attention à la propriété DidUnderstand de l'en-tête SOAP.

    Pour les en-têtes SOAP non définis par le service Web XML, la valeur initiale de DidUnderstand est false. Si ASP.NET détecte des en-têtes SOAP ayant false affecté à leur propriété DidUnderstand après le retour de la méthode de service Web XML, SoapHeaderException est automatiquement levé.

Pour gérer les en-têtes SOAP requis par un client de service Web XML et définis par le service Web XML

  • Procédez comme pour traiter les en-têtes SOAP dans un service Web XML créé à l'aide d'ASP.NET dans chaque méthode de service Web XML.

    Pour les en-têtes SOAP définis par le service Web XML et traités dans la méthode de service Web XML recevant l'en-tête SOAP, ASP.NET suppose que le service comprend l'en-tête et affecte true à la valeur initiale de DidUnderstand.

Le service Web XML MyWebService suivant définit l'en-tête SOAP MyHeader et exige qu'il soit envoyé avec les appels à la méthode de service Web XML MyWebMethod. De plus, MyWebMethod traite les en-têtes SOAP inconnus. Pour les en-têtes que MyWebMethod peut traiter, true est affecté à DidUnderstand.

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

Remarque   La propriété DidUnderstand est utilisée par ASP.NET pour communiquer avec la méthode de service Web XML. Elle ne fait pas partie de la spécification SOAP ; sa valeur n'apparaît dans aucune partie de la demande ni de la réponse SOAP.

Si un service Web XML transfère un en-tête SOAP, il est très important de suivre les règles de la spécification SOAP, en particulier celles relatives à la valeur de Actor. Pour plus d'informations, consultez le site Web du W3C (http://www.w3.org/TR/SOAP/).

Gestion des erreurs qui surviennent lors du traitement d'un en-tête SOAP

Lorsqu'un service Web XML détecte une erreur spécifique au traitement d'un en-tête, SoapHeaderException doit être levé. L'utilisation de cette classe d'exception permet aux services Web XML de mettre correctement la réponse en forme. Si le client est créé à l'aide du .NET Framework, il recevra SoapHeaderException, avec le contenu, y compris la propriété InnerException placée dans la propriété Message. La propriété InnerException du SoapHeaderException intercepté par le client sera null. C'est un modèle de programmation pris en charge par le .NET Framework puisque l'exception est envoyée sur le réseau dans un élément XML <Fault> SOAP comme cela est stipulé dans la spécification SOAP. Pour plus d'informations sur les exceptions, consultez Gestion et levée d'exceptions dans les services Web XML.

L'exemple de code suivant lève une exception SoapHeaderException si un client fait une demande SOAP à la méthode de service Web XML MyWebMethod en affectant la propriété Expires à une date et une heure passées au moment où la demande SOAP atteint le service Web XML.

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

Remarque : Le .NET Framework version 1.0 inclut la propriété SoapHeaderAttribute.Required qui permet à un service Web XML de demander qu'un client envoie un en-tête SOAP spécifique lorsqu'elle est définie à true. ASP.NET indique que l'en-tête SOAP est requis dans un document WSDL généré en définissant l'attribut wsdl:required à « true » dans l'élément soap:header. Les clients .NET Framework du service Web XML construit à partir du document WSDL reçoivent un SoapHeaderException s'ils n'envoient pas l'en-tête SOAP requis, et les autres clients reçoivent une erreur SOAP. Pour interagir avec d'autres implémentations SOAP, cette fonctionnalité est supprimée dans les versions ultérieures.

La propriété Required est obsolète à la version 1.1 et l'attribut wsdl:required d'un élément soap:header dans un document WSDL n'est pas pris en compte par l'outil du langage WSDL (Wsdl.exe). Comme un en-tête SOAP ne peut plus être exigé, un service Web XML doit vérifier que le champ ou la propriété représentant l'en-tête SOAP n'est pas null avant d'y accéder.

Voir aussi

SoapHeader | SoapHeaderAttribute | SoapHeaderException | SoapUnknownHeader | Création de services Web XML à l'aide d'ASP.NET | Création de clients de service Web XML