Comment : gérer des en-têtes SOAP requis par un client de service Web XML

Cette rubrique est spécifique à une technologie existante. Les services Web XML et les clients du service Web XML doivent à présent être créés à l'aide de Windows Communication Foundation.

Exemple de code

Un client peut demander à une méthode de service Web d'interpréter correctement la sémantique de l'en-tête SOAP et la traiter en conséquence pour que la demande SOAP réussisse. Pour ce faire, les clients affectent à l'attribut mustUnderstand de l'en-tête SOAP la valeur 1. Par exemple, la demande SOAP suivante demande au destinataire de la demande SOAP 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>

Le service Web gère différemment les en-tête SOAP requis par le client selon que le service Web définit ou non l'en-tête SOAP. ASP.NET gère une bonne partie du travail dans le cas où le service Web définit l'en-tête SOAP. Dans la procédure suivante, vous apprenez à gérer les deux cas.

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

1. Suivez les étapes pour gérer les en-têtes SOAP inconnus d'un client de service Web, en faisant particulièrement attention à la propriété DidUnderstand de l'en-tête SOAP.

   Dans le cas d'en-têtes SOAP non définis par le service Web, la valeur initiale de DidUnderstand est false. Si ASP.NET détecte des en-têtes SOAP dont la propriété DidUnderstand a la valeur false après le retour de la méthode de service Web, un SoapHeaderException est levé automatiquement.

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

1. Suivez les étapes du traitement des en-têtes SOAP dans un service Web créé à l'aide d'ASP.NET dans chaque méthode de service Web.

   Dans le cas d'un en-tête SOAP défini par le service Web et traité dans la méthode de service Web qui reçoit l'en-tête SOAP, ASP.NET suppose que le service Web comprend l'en-tête SOAP et attribue à DidUnderstand la valeur initiale true.

Exemple

Le service Web MyWebService suivant définit l'en-tête SOAP MyHeader et demande à l'envoyer avec tous les appels à la méthode de service Web MyWebMethod. En outre, MyWebMethod traite tous les en-têtes SOAP inconnus. Dans le cas des en-têtes SOAP que MyWebMethod peut traiter, DidUnderstand a la valeur true.

<%@ 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";
    }
}

<%@ 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. Elle ne fait pas partie de la spécification SOAP; sa valeur n'apparaît dans aucune partie de la demande SOAP ou de la réponse SOAP.

Remarque :
Si un service Web 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 qui ont rapport à la valeur du Actor. Pour plus d'informations, consultez le site Web W3C (http://www.w3.org/TR/SOAP/).

Voir aussi

Référence

SoapHeader
SoapHeaderAttribute
SoapUnknownHeader
SoapHeaderException

Concepts

Création de clients de service Web XML

Autres ressources

Utilisation d'en-têtes SOAP
Services Web XML utilisant ASP.NET