Behandeln und Auslösen von Ausnahmen in XML-Webdiensten

Artikel
03/31/2008

Ausnahmen, die von einer mit ASP.NET erstellten XML-Webdienstmethode ausgelöst werden, werden in Form eines SOAP-Fehlers an den Client zurückgesendet. Ein SOAP-Fehler ist ein in einer SOAP-Meldung enthaltenes XML-Element <Fault>, durch das das Auftreten eines Fehlers angezeigt wird. Beim Übermitteln eines SOAP-Fehlers verwendet ASP.NET dieselbe Methode, die von der SOAP-Spezifikation für die Rückgabe von Fehlern an den Client vorgegeben wird. Das SOAP-XML-Element <Fault> enthält Detailinformationen, wie die Ausnahmezeichenfolge und die Quelle der Ausnahme. Ausführliche Informationen zu SOAP-Fehlern finden Sie auf der W3C-Website unter http://www.w3.org/TR/SOAP (nur auf Englisch verfügbar).

Das XML-Element <Fault> wird weder von Clients noch von XML-Webdiensten, die mit ASP.NET erstellt wurden, direkt gefüllt oder analysiert; beide verwenden das allgemeine, in .NET Framework enthaltene Entwurfsmuster für das Auslösen und Abfangen von Ausnahmen. Ein XML-Webdienst kann entweder eine problemspezifische Ausnahme, z. B. ArgumentOutOfRangeException, oder aber eine SoapException auslösen. In beiden Fällen serialisiert ASP.NET die Ausnahme in eine gültige SOAP-Meldung, indem die Ausnahme einem SOAP-Fehlerelement hinzugefügt wird. Wenn die SOAP-Meldung auf einem ASP.NET-Client deserialisiert wird, wird der SOAP-Fehler in eine SoapException-Ausnahme konvertiert, wobei die Ausnahmedetails in die Message-Eigenschaft eingefügt werden. Ein Client kann folglich einen Try/Catch-Block für das Abfangen einer SoapException einrichten.

Eine Webanwendung kann mehrere XML-Webdienste umfassen. Das Application_Error-Ereignis in der Datei Global.asax kann für die globale Ausnahmebehandlung jedoch nicht verwendet werden. Der HttpHandler für XML-Webdienste verarbeitet jede Ausnahme, die beim Ausführen eines XML-Webdienstes auftritt, und wandelt sie vor dem Aufrufen des Application_Error-Ereignisses in einen SOAP-Fehler um. Erstellen Sie eine SOAP-Erweiterung, um Ausnahmen von XML-Webdiensten in einem globalen Ausnahmehandler zu verarbeiten. Eine SOAP-Erweiterung kann das Vorhandensein einer Ausnahme in der ProcessMessage-Methode überprüfen. Überprüfen Sie in der ProcessMessage-Methode die Exception-Eigenschaft von SoapMessage, die übergeben wird, wenn die Stage-Eigenschaft auf AfterSerialize festgelegt ist. Ausführliche Informationen zu SOAP-Erweiterungen finden Sie unter Ändern der SOAP-Meldung mit SOAP-Erweiterungen.

Auslösen von Ausnahmen von einem XML-Webdienst, der mit ASP.NET erstellt wurde

Fehler werden durch das Auslösen von Ausnahmen zurück an einen Client übermittelt. Einer XML-Webdienstmethode stehen dazu vier Möglichkeiten zur Verfügung:

Auslösen einer SoapException-Ausnahme
Auslösen einer SoapHeaderException-Ausnahme
Auslösen einer problemspezifischen Ausnahme
Auslösen der Ausnahme durch ASP.NET

In der folgenden Tabelle wird beschrieben, welche Ausnahmen von einem XML-Webdienst explizit ausgelöst werden können und wie die einzelnen Ausnahmen von einem ASP.NET-Client empfangen werden.

Typ der ausgelösten Ausnahme	Mögliche Aktionen eines XML-Webdienstes
Andere Ausnahmen als SoapException oder SoapHeaderException	Eine XML-Webdienstmethode erkennt einen Ausnahmefall und übergibt die ausgelöste Ausnahme, z. B. ArgumentOutOfRangeException, zurück an den Client. Ein ASP.NET-Client empfängt eine SoapException, deren Details in der Message-Eigenschaft in Textform serialisiert sind.
SoapException	Eine XML-Webdienstmethode erkennt einen Ausnahmefall und löst eine SoapException aus. Darüber hinaus stellt sie zusätzliche problemspezifische Details zur Verfügung. Die XML-Webdienstmethode füllt die Detail-Eigenschaft mit Daten, um diese zusätzlichen Informationen bereitzustellen. Ein ASP.NET-Client empfängt die SoapException mit den zusätzlichen Informationen.
SoapHeaderException	Eine XML-Webdienstmethode erkennt bei der Verarbeitung eines SOAP-Headers einen Ausnahmefall. Die XML-Webdienstmethode muss eine ausgelöste SoapHeaderException entsprechend der SOAP-Spezifikation an den Client zurückgeben. Ein ASP.NET-Client empfängt die SoapHeaderException.

So lösen Sie eine Ausnahme von einem XML-Webdienst aus

Lösen Sie die problemspezifische Ausnahme, wie SoapException oder SoapHeaderException, entsprechend den Hinweisen in der vorangehenden Tabelle aus.

Im folgenden Codebeispiel werden eine SoapException ausgelöst und zusätzliche Details zur Ausnahme angegeben, indem die Detail-Eigenschaft festgelegt wird.

<%@ WebService Language="VB" class="ThrowSoapException"%>

Imports System
Imports System.Web.Services
Imports System.Web.Services.Protocols
Imports System.Xml.Serialization
Imports System.Xml

Public Class ThrowSoapException
    Inherits WebService

    ' This XML Web service method throws a SOAP client fault code. 
    <WebMethod()> _
    Public Sub myThrow()

        ' Build the detail element of the SOAP fault.
        Dim doc As New System.Xml.XmlDocument()
        Dim node As System.Xml.XmlNode = _            doc.CreateNode(XmlNodeType.Element, _            SoapException.DetailElementName.Name, _            SoapException.DetailElementName.Namespace)

        ' Build specific details for the SoapException.
        ' Add first child of detail XML element.
        Dim details As System.Xml.XmlNode = _             doc.CreateNode(XmlNodeType.Element, _            "mySpecialInfo1", "http://tempuri.org/")

        ' Add second child of detail XML element with an attribute.
        Dim details2 As System.Xml.XmlNode = _            doc.CreateNode(XmlNodeType.Element, _            "mySpecialInfo2", "http://tempuri.org/")
        Dim attr As XmlAttribute = doc.CreateAttribute("t", _ 
            "attrName", "http://tempuri.org/")
        attr.Value = "attrValue"
        details2.Attributes.Append(attr)

        ' Append the two child elements to the detail node.
        node.AppendChild(details)
        node.AppendChild(details2)

        'Throw the exception.
        Dim se As New SoapException("Fault occurred", _            SoapException.ClientFaultCode, _            Context.Request.Url.AbsoluteUri, node)
        Throw se
        Return
    End Sub
End Class
[C#]
<%@ WebService Language="C#" class="ThrowSoapException"%>

using System;
using System.Web.Services;
using System.Web.Services.Protocols;
using System.Xml.Serialization;
using System.Xml;

public class ThrowSoapException : WebService 
{
    // This XML Web service method throws a SOAP client fault code.
    [WebMethod]
    public void myThrow(){

        // Build the detail element of the SOAP fault.
        System.Xml.XmlDocument doc = new System.Xml.XmlDocument();
        System.Xml.XmlNode node = doc.CreateNode(XmlNodeType.Element,             SoapException.DetailElementName.Name,              SoapException.DetailElementName.Namespace);

        // Build specific details for the SoapException.
        // Add first child of detail XML element.
        System.Xml.XmlNode details =
          doc.CreateNode(XmlNodeType.Element, "mySpecialInfo1",
                         "http://tempuri.org/");
        System.Xml.XmlNode detailsChild =           doc.CreateNode(XmlNodeType.Element, "childOfSpecialInfo",                         "http://tempuri.org/");
        details.AppendChild(detailsChild);

        // Add second child of detail XML element with an attribute.
        System.Xml.XmlNode details2 =          doc.CreateNode(XmlNodeType.Element, "mySpecialInfo2",                         "http://tempuri.org/");
        XmlAttribute attr = doc.CreateAttribute("t", "attrName",
                            "http://tempuri.org/");
        attr.Value = "attrValue";
        details2.Attributes.Append(attr);

        // Append the two child elements to the detail node.
        node.AppendChild(details);
        node.AppendChild(details2);

        //Throw the exception            SoapException se = new SoapException("Fault occurred",          SoapException.ClientFaultCode,          Context.Request.Url.AbsoluteUri ,          node);

        throw se;
        return;
    }
}

So fangen Sie eine von einer XML-Webdienstmethode ausgelöste Ausnahme ab

Fangen Sie innerhalb eines Try/Catch-Blockes die SoapException ab (alle von einer XML-Webdienstmethode ausgelösten Ausnahmen werden als SoapException ausgelöst).

Im folgenden Codebeispiel, in dem eine XML-Webdienstmethode von einem Client aufgerufen wird, wird die von der XML-Webdienstmethode ausgelöste Ausnahme abgefangen. Der Client füllt daraufhin eine HTML-Tabelle mit den Eigenschaften der abgefangenen SoapException.

<%@ Import Namespace="System.Web.Services.Protocols" %>
<%@ Import Namespace="System.Xml" %>
<%@ Page Language="vb" %>
<html>
 <head>
 <script runat=server language=vb>
    Sub Page_Load(o As Object, e As EventArgs)
       ' Create a new instance of the XML Web service class.
       Dim ThrowsSoapException As ThrowSoapException = New _
                 ThrowSoapException()
       Try
         ThrowsSoapException.myThrow()
       Catch myerr As SoapException
            ' Populate the table with the exception details.
            ErrorTable.Rows.Add(BuildNewRow("Fault Code Namespace", _
                                myerr.Code.Namespace))
            ErrorTable.Rows.Add(BuildNewRow("Fault Code Name", _
                                myerr.Code.Name))
            ErrorTable.Rows.Add(BuildNewRow( _
              "SOAP Actor that threw Exception", myerr.Actor))
            ErrorTable.Rows.Add(BuildNewRow("Error Message", _
                                 myerr.Message))
            ErrorTable.Rows.Add(BuildNewRow("Detail", _
                HttpUtility.HtmlEncode(myerr.Detail.OuterXml) )) 
            Return
        End Try
    End Sub 'Page_Load

    Function BuildNewRow(Cell1Text As String, Cell2Text As String) _
             As HtmlTableRow
        Dim row As New HtmlTableRow()
        Dim cell1 As New HtmlTableCell()
        Dim cell2 As New HtmlTableCell()

        'Set the contents of the two cells.
        cell1.Controls.Add(New LiteralControl(Cell1Text))
        'Add the cells to the row.
        row.Cells.Add(cell1)

        cell2.Controls.Add(New LiteralControl(Cell2Text))

        'Add the cells to the row.
        row.Cells.Add(cell2)
        Return row
    End Function 'BuildNewRow 
 </script>
 <head>
 <body>
     <table id="ErrorTable" CellPadding=5 CellSpacing=0 Border="1" BorderColor="black" runat="server" />
 </body>
[C#]
<%@ Import Namespace="System.Web.Services.Protocols" %>
<%@ Import Namespace="System.Xml" %>
<%@ Page Language="C#" %>
<html>
 <head>
 <script runat=server language=c#>
 void Page_Load(Object o, EventArgs e){

   // Create a new instance of the XML Web service proxy class.
   ThrowSoapException throwSoapException = new ThrowSoapException();

   // Make a call to the XML Web service method, which throws an
   // exception.
    try
    {
       throwSoapException.myThrow();
    }
    catch (SoapException error)     {
       // Populate the table with the exception details.
       ErrorTable.Rows.Add(BuildNewRow("Fault Code Namespace",
                                        error.Code.Namespace));
       ErrorTable.Rows.Add(BuildNewRow("Fault Code Name",
                                        error.Code.Name)); 
       ErrorTable.Rows.Add(BuildNewRow(
          "SOAP Actor that threw Exception", error.Actor));
       ErrorTable.Rows.Add(BuildNewRow("Error Message",
           error.Message));
       ErrorTable.Rows.Add(BuildNewRow("Detail",
           HttpUtility.HtmlEncode(error.Detail.OuterXml)));

       return;
     }

 }
// This populates a row in an HtmlTable.
 HtmlTableRow BuildNewRow(string Cell1Text, string Cell2Text) {
     HtmlTableRow row = new HtmlTableRow();
     HtmlTableCell cell1 = new HtmlTableCell();
     HtmlTableCell cell2 = new HtmlTableCell();

     //Set the contents of the two cells.
     cell1.Controls.Add(new LiteralControl(Cell1Text));
     //Add a cell to the row.
     row.Cells.Add(cell1);

     cell2.Controls.Add(new LiteralControl(Cell2Text));

     //Add a cell to the row.
     row.Cells.Add(cell2);
     return row;

 }
 </script>
 <head>
 <body>
     <table id="ErrorTable" CellPadding=5 CellSpacing=0 Border="1" BorderColor="black" runat="server" />
 </body>

Von einer XML-Webdienstmethode nicht behandelte Ausnahmen

Der folgenden Tabelle können Sie entnehmen, wie eine Ausnahme von ASP.NET behandelt wird, wenn eine innerhalb der Methode aufgetretene Ausnahme von einer XML-Webdienstmethode nicht abgefangen wird.

Zeitpunkt des Auftretens einer unbehandelten Ausnahme	Von ASP.NET ausgeführte Aktion
Beim Ausführen der XML-Webdienstmethode	Die Ausnahme wird von ASP.NET abgefangen und zurück an den Client übergeben. Der mit .NET Framework erstellte XML-Webdienstclient empfängt eine SoapException mit der spezifischen Ausnahme, die in der InnerException-Eigenschaft enthalten ist.
Beim Verarbeiten von SOAP-Headern	ASP.NET löst eine SoapHeaderException aus. Ein mit .NET Framework erstellter XML-Webdienstclient empfängt die SoapHeaderException.

Siehe auch

SoapException-Klasse | SoapHeaderException-Klasse | Behandeln und Auslösen von Ausnahmen | Erstellen von XML-Webdiensten mit ASP.NET | Erstellen von XML-Webdienstclients

Freigeben über

Behandeln und Auslösen von Ausnahmen in XML-Webdiensten

Auslösen von Ausnahmen von einem XML-Webdienst, der mit ASP.NET erstellt wurde

Von einer XML-Webdienstmethode nicht behandelte Ausnahmen

Siehe auch

Zusätzliche Ressourcen