Freigeben über

Verwenden von SOAP-Headern

Die Kommunikation mit einer XML-Webdienstmethode mittels SOAP basiert auf einem Standardformat. Einen Teil dieses Formats bilden die Daten, die in einem XML-Dokument codiert sind. Das XML-Dokument besteht aus einem Envelope-Stammtag, das wiederum aus einem erforderlichen Body-Element und einem optionalen Header-Element besteht. Das Body-Element umfasst die meldungsspezifischen Daten. Das optionale Header-Element kann zusätzliche Informationen enthalten, die sich nicht direkt auf eine bestimmte Meldung beziehen. Jedes untergeordnete Element des Header-Elements wird als SOAP-Header bezeichnet.

Grundsätzlich ist es möglich, dass SOAP-Header zur Meldung gehörige Daten enthalten, da der Inhalt eines SOAP-Headers durch die SOAP-Spezifikation nicht streng vorgegeben wird. Normalerweise enthalten die Header jedoch Informationen, die innerhalb eines Webservers von der Infrastruktur verarbeitet werden. Ein SOAP-Header könnte beispielsweise verwendet werden, um Routinginformationen für die SOAP-Meldung darin anzugeben.

Definieren und Verarbeiten von SOAP-Headern

SOAP-Header können durch XML-Webdienste, die mit ASP.NET erstellt wurden, definiert und bearbeitet werden. Zur Definition eines SOAP-Headers wird eine Klasse definiert, die die Daten in einem bestimmten SOAP-Header darstellt und die von der SoapHeader-Klasse abgeleitet wird.

So definieren Sie eine Klasse, die einen SOAP-Header darstellt

  1. Erstellen Sie eine von der SoapHeader-Klasse abgeleitete Klasse, deren Name dem Stammelement für den SOAP-Header entspricht.

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

  2. Fügen Sie öffentliche Felder oder Eigenschaften hinzu, und ordnen Sie für jedes Element im SOAP-Header Namen und entsprechende Datentypen einander zu.

    Beim folgenden SOAP-Header würde durch die darauf folgende Klasse eine Klasse definiert werden, die den SOAP-Header darstellt.

    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

So verarbeiten Sie SOAP-Header innerhalb eines XML-Webdienstes

  1. Fügen Sie der Klasse, die den XML-Webdienst entsprechend dem durch den SOAP-Header dargestellten Typ implementiert, einen öffentlichen Member hinzu.

    [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. Wenden Sie auf jede XML-Webdienstmethode, durch die der SOAP-Header verarbeitet werden soll, ein SoapHeader-Attribut an. Setzen Sie die MemberName-Eigenschaft des SoapHeader-Attributs auf den Namen der in Schritt 1 erstellten Membervariablen.

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

  3. Greifen Sie innerhalb der einzelnen XML-Webdienstmethoden, auf die das SoapHeader-Attribut angewendet wird, auf die unter Schritt 1 erstellte Membervariable zu, um die im SOAP-Header gesendeten Daten zu verarbeiten.

    [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

Im folgenden Codebeispiel wird veranschaulicht, wie Sie einen SOAP-Header in einem mit ASP.NET erstellten XML-Webdienst definieren und verarbeiten. Der XML-Webdienst MyWebService verfügt über eine Membervariable namens timeStamp, die einen von SoapHeader (MyHeader) abgeleiteten Typ aufweist und die auf die MemberName-Eigenschaft des SoapHeader-Attributs gesetzt ist. Zusätzlich wird ein SoapHeader-Attribut auf die XML-Webdienstmethode MyWebMethod angewendet, durch die myHeaderMemberVariable festgelegt wird. In der XML-Webdienstmethode MyWebMethod wird auf myHeaderMemberVariable zugegriffen, um den Wert der XML-Elemente Created und Expires des SOAP-Headers festzulegen.

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

Im vorherigen Beispiel wird eine SOAP-Antwort an den Client zurückgegeben, wobei das Expires-Element auf 60000 (Millisekunden, d. h. 1 Minute) festgelegt und das Created-Element auf die aktuelle Uhrzeit in koordinierter Weltzeit. Das heißt, die folgende SOAP-Antwort wird an den Client gesendet.

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

Erstellen eines Clients, der SOAP-Header verarbeitet

Ein XML-Webdienstclient kann SOAP-Header bei der Kommunikation mit einem XML-Webdienst senden und empfangen. Wenn eine Proxyklasse mit dem Dienstprogramm Wsdl.exe für einen XML-Webdienst erstellt wird, der SOAP-Header erwartet oder zurückgibt, enthält die Proxyklasse Informationen über die SOAP-Header. Die Proxyklasse verfügt also genauer ausgedrückt über Membervariablen, die die SOAP-Header darstellen, die mit den SOAP-Headern im XML-Webdienst in Wechselbeziehung stehen. Die Proxyklasse verfügt außerdem über Definitionen für die entsprechenden Klassen, die die SOAP-Header darstellen. Die für den vorherigen XML-Webdienst erstellten Proxyklassen enthalten beispielsweise eine Membervariable vom Typ MyHeader sowie eine Definition für die MyHeader-Klasse. Ausführliche Informationen zum Erstellen einer Proxyklasse finden Sie unter Erstellen eines XML-Webdienstproxys.

Hinweis: Wenn der XML-Webdienst die Membervariablen definiert, die SOAP-Header vom Typ SoapHeader oder SoapUnknownHeader und keine von SoapHeader abgeleitete Klasse darstellen, enthält die Proxyklasse keine Informationen über diesen SOAP-Header.

So verarbeiten Sie SOAP-Header innerhalb eines XML-Webdienstclients

  1. Erstellen Sie eine neue Instanz der Klasse, die den SOAP-Header darstellt.

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

  2. Geben Sie die Werte für den SOAP-Header an.

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

  3. Erstellen Sie eine neue Instanz der Proxyklasse.

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

  4. Weisen Sie der Membervariablen der Proxyklasse, die den SOAP-Header darstellt, das SOAP-Headerobjekt zu.

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

  5. Rufen Sie die Methode für die Proxyklasse auf, die mit der XML-Webdienstmethode kommuniziert.

    Der SOAP-Headerbereich der an den XML-Webdienst gesendeten SOAP-Anforderung enthält den Inhalt der im SOAP-Headerobjekt gespeicherten Daten.

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

Im folgenden Codebeispiel wird veranschaulicht, wie Sie einen SOAP-Header von einem Client an einen XML-Webdienst übergeben.

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

Ändern der Empfänger von SOAP-Headern

SOAP-Header werden automatisch von einem XML-Webdienstclient an eine XML-Webdienstmethode gesendet, nachdem ein SoapHeader-Attribut auf eine XML-Webdienstmethode angewendet wurde. Ein SOAP-Header kann von der XML-Webdienstmethode jedoch auch zurück an den XML-Webdienstclient gesendet werden. Der Header kann auch bidirektional gesendet werden. Durch das Festlegen der Direction-Eigenschaft eines SoapHeader-Attributs, das auf eine XML-Webdienstmethode angewendet wird, wird gesteuert, an welche Empfänger der SOAP-Header gesendet wird. Die Direction-Eigenschaft hat den Typ SoapHeaderDirection, der über die vier Werte In, Out, InOut und Fault verfügt. Diese beziehen sich jeweils auf den Empfänger (ob es sich um den XML-Webdienstserver handelt), auf den Client, oder sowohl auf den XML-Webdienstserver als auch den Client und darauf, ob der SOAP-Header beim Auslösen einer Ausnahme durch den XML-Webdienstserver an den Client gesendet wird.

Hinweis: Version 1.0 von .NET Framework SDK unterstützt den Fault-Wert nicht.

So ändern Sie den Empfänger des SOAP-Headers

  1. Definieren Sie den SOAP-Header.

    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. Fügen Sie der Klasse, durch die der XML-Webdienst implementiert wird, eine Membervariable hinzu.

    [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. Wenden Sie auf jede XML-Webdienstmethode, die den SOAP-Header verarbeitet, ein SoapHeader-Attribut an. Legen Sie die Direction-Eigenschaft für die einzelnen beabsichtigten Empfänger fest, indem Sie die SoapHeaderDirection-Enumeration verwenden. Im folgenden Beispiel wird der XML-Webdienstclient als Empfänger festgelegt, indem Direction auf SoapHeaderDirection.Out gesetzt wird.

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

  4. Je nach Empfänger können Sie den SOAP-Header jetzt verarbeiten oder festlegen. Im folgenden Codebeispiel werden die Werte des SOAP-Headers festgelegt, da es sich beim Empfänger um den XML-Webdienstclient handelt.

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

Im folgenden Codebeispiel wird der SOAP-Header MyHeader definiert, der von der XML-Webdienstmethode an den Client gesendet wird.

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

Behandeln unbekannter SOAP-Header

Ein XML-Webdienstclient kann eine SOAP-Anforderung mit einem SOAP-Header an eine XML-Webdienstmethode senden, während der SOAP-Header vom XML-Webdienst möglicherweise nicht explizit erwartet wurde. In diesem Fall sollte festgestellt werden, ob die Semantik des SOAP-Headers verstanden und verarbeitet wird. Gemäß der SOAP-Spezifikation wird eine Ausnahme ausgelöst, wenn SOAP-Header über ein mustUnderstand-Attribut mit dem Wert true verfügen. Einzelheiten zum Behandeln von SOAP-Headern, die von einem Client benötigt werden, finden Sie unter Behandeln von SOAP-Headern, die von einem XML-Webdienstclient benötigt werden.

So behandeln Sie unbekannte SOAP-Header von einem XML-Webdienstclient aus

  1. Fügen Sie der Klasse, durch die der XML-Webdienst implementiert wird, eine Membervariable vom Typ SoapUnknownHeader oder SoapHeader bzw. ein Array aus beiden hinzu, um mehrere unbekannte SOAP-Header zu behandeln.

    Die Deklaration des Typs als Array oder als einzelne Instanz von SoapUnknownHeader hat den zusätzlichen Vorteil, dass SoapUnknownHeader über eine Element-Eigenschaft verfügt. Die Element-Eigenschaft ist vom Typ XmlElement und stellt das XML-Dokument für das Header-Element der SOAP-Anforderung bzw. SOAP-Antwort dar. Eine XML-Webdienstmethode kann folglich den Namen des SOAP-Headers zusammen mit den vom SOAP-Header übermittelten Daten ermitteln, indem sie die Element-Eigenschaft abfragt.

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

  2. Wenden Sie auf jede XML-Webdienstmethode, die die Verarbeitung aller unbekannten SOAP-Header beabsichtigt, ein SoapHeader-Attribut an.

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

  3. Fügen Sie Code hinzu, um festzustellen, ob Sie unbekannte SOAP-Header verarbeiten können.

    Wenn die Membervariable den Typ SoapUnknownHeader aufweist, kann eine XML-Webdienstmethode den Namen des SOAP-Headers zusammen mit den vom SOAP-Header übermittelten Daten ermitteln, indem sie die Element-Eigenschaft abfragt. Durch die Name-Eigenschaft der Element-Eigenschaft wird der Name des SOAP-Headers identifiziert.

           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. Legen Sie die DidUnderstand-Eigenschaft der Membervariablen, die den unbekannten SOAP-Header darstellt, auf true fest, wenn bekannt ist, wie ein bestimmter SOAP-Header verarbeitet wird.

    Wenn eine XML-Webdienstmethode einen unbekannten SOAP-Header verarbeitet und die DidUnderstand-Eigenschaft nicht auf true festlegt, kann eine SoapHeaderException ausgelöst werden. Ausführliche Informationen erhalten Sie unter Behandeln von SOAP-Headern, die von einem XML-Webdienstclient benötigt werden.

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

    Hinweis   Die DidUnderstand-Eigenschaft wird von den mit ASP.NET erstellten XML-Webdiensten für die Kommunikation mit der XML-Webdienstmethode verwendet. Diese Eigenschaft ist in der SOAP-Spezifikation nicht enthalten. Ihr Wert kommt in der SOAP-Anforderung bzw. SOAP-Antwort nicht vor.

    Hinweis   Wenn eine Proxyklasse von einem XML-Webdienstclient mit dem Web Services Description Language-Tool (Wsdl.exe) erstellt und die Membervariable, die einen SOAP-Header darstellt, von einem XML-Webdienst mit dem Typ SoapUnknownHeader definiert wird, wird der Proxyklasse kein Verweis auf diesen SOAP-Header hinzugefügt. Wenn ein XML-Webdienstclient entscheidet, diesen SOAP-Header der SOAP-Anforderung hinzuzufügen, muss die Proxyklasse angepasst werden, indem eine Membervariable hinzugefügt und ein SoapHeader-Attribut auf die Methode angewendet wird, die den Aufruf der zugehörigen XML-Webdienstmethode ausführt.

Behandeln von SOAP-Headern, die von einem XML-Webdienstclient benötigt werden

Ein Client kann u. U. erfordern, dass eine XML-Webdienstmethode die Semantik des SOAP-Headers richtig interpretiert und angemessen verarbeitet, damit die SOAP-Anforderung erfolgreich verläuft. Zu diesem Zweck müssen Clients das mustUnderstand-Attribut des SOAP-Headers auf 1 setzen. Die folgende SOAP-Anforderung erfordert vom Empfänger der SOAP-Anforderung beispielsweise, dass der SOAP-Header MyCustomSoapHeader verarbeitet wird.

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

Wie der XML-Webdienst die vom Client benötigten SOAP-Header behandelt, hängt davon ab, ob der SOAP-Header vom XML-Webdienst definiert wird oder nicht. Für den Fall, dass der SOAP-Header vom XML-Webdienst definiert wird, führt ASP.NET einen Großteil der Arbeit aus. Der folgenden Prozedur können Sie entnehmen, wie die beiden Fälle behandelt werden.

So behandeln Sie vom XML-Webdienst nicht definierte, aber von einem XML-Webdienstclient benötigte SOAP-Header

  • Führen Sie die Schritte zur Behandlung unbekannter SOAP-Header von einem XML-Webdienstclient aus, und achten Sie besonders auf die DidUnderstand-Eigenschaft des SOAP-Headers.

    Bei SOAP-Headern, die nicht vom XML-Webdienst definiert wurden, ist der Anfangswert von DidUnderstand auf false gesetzt. Wenn ASP.NET nach der Rückkehr der XML-Webdienstmethode SOAP-Header ermittelt, deren DidUnderstand-Eigenschaft auf false gesetzt ist, wird automatisch eine SoapHeaderException ausgelöst.

So behandeln Sie von einem XML-Webdienstclient benötigte und vom XML-Webdienst definierte SOAP-Header

  • Führen Sie innerhalb jeder XML-Webdienstmethode die Schritte für die Verarbeitung von SOAP-Headern in einem mit ASP.NET erstellten XML-Webdienst aus.

    Bei SOAP-Headern, die vom XML-Webdienst definiert und in der XML-Webdienstmethode, die den SOAP-Header empfängt, verarbeitet werden, setzt ASP.NET voraus, dass der XML-Webdienst den SOAP-Header versteht, und setzt den Anfangswert von DidUnderstand auf true.

Vom folgenden XML-Webdienst MyWebService wird der SOAP-Header MyHeader definiert, und es wird festgelegt, dass dieser bei jedem Aufruf der XML-Webdienstmethode MyWebMethod mitgesendet werden muss. Darüber hinaus verarbeitet MyWebMethod alle unbekannten SOAP-Header. Bei SOAP-Headern, die von MyWebMethod verarbeitet werden können, wird DidUnderstand auf true festgelegt.

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

Hinweis   Die DidUnderstand-Eigenschaft wird von ASP.NET verwendet, um mit der XML-Webdienstmethode zu kommunizieren. Diese Eigenschaft ist in der SOAP-Spezifikation nicht enthalten; ihr Wert kommt weder in der SOAP-Anforderung noch in der SOAP-Antwort vor.

Wenn ein XML-Webdienst einen SOAP-Header weiterleitet, müssen die Richtlinien in der SOAP-Spezifikation unbedingt beachtet werden, insbesondere jene, die den Wert von Actor betreffen. Ausführliche Informationen finden Sie auf der W3C-Website unter http://www.w3.org/TR/SOAP/ (nur auf Englisch verfügbar).

Behandeln von Fehlern, die bei der Verarbeitung eines SOAP-Headers auftreten

Wenn ein XML-Webdienst einen Fehler erkennt, der spezifisch für die Verarbeitung des Headers ist, sollte eine SoapHeaderException ausgelöst werden. Diese Ausnahmeklasse ermöglicht XML-Webdiensten die richtige Formatierung der Antwort. Wenn der Client mit Hilfe von .NET Framework erstellt wird, empfängt er die SoapHeaderException mit ihrem Inhalt, einschließlich der InnerException-Eigenschaft, die sich in der Message-Eigenschaft befindet. Die InnerException-Eigenschaft der vom Client abgefangenen SoapHeaderException ist null. Dieses Programmiermodell wird von .NET Framework unterstützt, da die Ausnahme im SOAP-XML-Element <Fault> im Netzwerk gesendet wird, wie in der SOAP-Spezifikation vorgegeben. Ausführliche Informationen zu Ausnahmen finden Sie unter Behandeln und Auslösen von Ausnahmen in XML-Webdiensten.

Das folgende Codebeispiel löst eine SoapHeaderException-Ausnahme aus, wenn ein Client eine SOAP-Anforderung an die MyWebMethod-XML-Webdienstmethode sendet, die die Expires-Eigenschaft auf einen Zeitpunkt (Datum und Uhrzeit) festlegt, der bereits vergangen ist, wenn die SOAP-Anforderung den XML-Webdienst erreicht.

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

Hinweis: .NET Framework, Version 1.0, enthält die SoapHeaderAttribute.Required-Eigenschaft, mit der ein XML-Webdienst fordern kann, dass ein Client einen bestimmten SOAP-Header sendet, wenn die Eigenschaft auf true festgelegt ist. ASP.NET gibt an, dass der SOAP-Header in einem erstellten WSDL-Dokument erforderlich ist, indem das wsdl:required-Attribut im soap:header-Element auf "true" festgelegt wird. .NET Framework-Clients des aus dem WSDL-Dokument erstellten XML-Webdienstes empfangen eine SoapHeaderException, wenn Sie den erforderlichen SOAP-Header nicht senden und andere Clients einen SOAP-Fehler empfangen. Um mit anderen SOAP-Implementierungen zusammenwirken zu können, wurde diese Funktionalität in späteren Versionen entfernt.

Die Required-Eigenschaft ist in Version 1.1 veraltet, und das wsdl:required-Attribut eines soap:header-Elements in einem WSDL-Dokument wird vom Web Services Description Language-Tool (Wsdl.exe) ignoriert. Da ein SOAP-Header nicht länger erforderlich sein kann, sollte ein XML-Webdienst vor dem Zugriff sicherstellen, dass das den SOAP-Header darstellende Feld oder die entsprechende Eigenschaft nicht null ist.

Siehe auch

SoapHeader | SoapHeaderAttribute | SoapHeaderException | SoapUnknownHeader | Erstellen von XML-Webdiensten mit ASP.NET | Erstellen von XML-Webdienstclients

  • Last updated on