Definieren und Angeben von Fehlern

  • Artikel

SOAP-Fehler vermitteln Informationen zu Fehlerbedingungen auf interoperable Weise von einem Dienst an einen Client und bei Duplexkommunikation von einem Client an einen Dienst. In diesem Thema wird beschrieben, wann und wie Sie benutzerdefinierten Fehlerinhalt definieren und wie Sie angeben, welche Vorgänge diesen zurückgeben können. Weitere Informationen über dazu, wie ein Dienst oder ein Duplexclient diese Fehler senden kann und wie eine Client- oder Dienstanwendung diese Fehler verarbeitet, finden Sie unter Senden und Empfangen von Fehlern. Eine Übersicht über die Fehlerbehandlung bei Windows Communication Foundation (WCF)-Anwendungen finden Sie unter Angeben und Behandeln von Fehlern in Verträgen und Diensten.

Übersicht

Bei deklarierten SOAP-Fehlern verfügt ein Vorgang über ein System.ServiceModel.FaultContractAttribute, das einen benutzerdefinierten SOAP-Fehlertyp angibt. Nicht deklarierte SOAP-Fehler sind Fehler, die nicht im Vertrag eines Vorgangs festgelegt sind. Dieses Thema enthält Informationen zur Identifizierung der Fehlerbedingungen und zur Erstellung eines Fehlervertrags für Ihren Dienst, den Clients verwenden können, um die Fehlerbedingungen richtig zu verarbeiten, wenn sie anhand von benutzerdefinierten SOAP-Fehlern darüber informiert werden. Die folgenden grundlegenden Aufgaben gelten in dieser Reihenfolge:

  1. Definieren Sie die Fehlerbedingungen, über die ein Client Ihres Dienstes informiert werden sollte.

  2. Definieren Sie für diese Fehlerbedingungen den benutzerdefinierten Inhalt der SOAP-Fehler.

  3. Kennzeichnen Sie Ihre Vorgänge, damit die spezifischen SOAP-Fehler, die diese Vorgänge auslösen, für Clients in WSDL offengelegt werden.

Definieren von Fehlerbedingungen, über die Clients informiert werden sollen

SOAP-Fehler sind öffentlich beschriebene Meldungen, die Fehlerinformationen für einen besonderen Vorgang enthalten. Da sie zusammen mit anderen Vorgangsmeldungen in WSDL beschrieben sind, sind Clients darüber informiert und erwarten beim Aufrufen eines Vorgangs, dass sie diese ggf. verarbeiten müssen. Da WCF-Dienste jedoch in verwaltetem Code geschrieben sind, ermöglicht es Ihnen die Entscheidung, welche Fehlerbedingungen in verwaltetem Code in Fehler konvertiert und an den Client zurückgegeben werden, Fehlerbedingungen und Fehler in Ihrem Dienst von der formalen Fehlerkonversation mit einem Client zu trennen.

Das folgende Codebeispiel zeigt zum Beispiel einen Vorgang, bei dem zwei ganze Zahlen verwendet und eine weitere ganze Zahl zurückgegeben wird. Hierbei können mehrere Ausnahmen ausgelöst werden. Beim Entwerfen des Fehlervertrags müssen Sie deshalb bestimmen, welche Fehlerbedingungen für Ihren Client wichtig sind. In diesem Fall muss der Dienst die System.DivideByZeroException-Ausnahme erkennen.

[ServiceContract]
public class CalculatorService
{
    [OperationContract] 
    int Divide(int a, int b)
    {
      if (b==0) throw new Exception("Division by zero!");
      return a/b;
    }
}

<ServiceContract> _
Public Class CalculatorService
    <OperationContract]> _
    Public Function Divide(ByVal a As Integer, ByVal b As Integer) _
       As Integer
      If (b==0) Then 
            Throw New Exception("Division by zero!")
      Return a/b
    End Function
End Class

Im obigen Beispiel kann der Vorgang entweder einen benutzerdefinierten SOAP-Fehler zurückgeben, der für die Division durch 0 gilt, einen benutzerdefinierten Fehler, der für mathematische Operationen gilt, aber Informationen zur Division durch 0 enthält, mehrere Fehler für verschiedene Fehlersituationen oder keinen SOAP-Fehler.

Definieren des Inhalts von Fehlerbedingungen

Nachdem eine Fehlerbedingung als Bedingung identifiziert wurde, die auf nützliche Weise einen benutzerdefinierten SOAP-Fehler zurückgeben kann, besteht der nächste Schritt darin, den Inhalt dieses Fehlers zu definieren und sicherzustellen, dass die Inhaltsstruktur serialisiert werden kann. Das Codebeispiel im vorherigen Abschnitt zeigt einen Fehler, der spezifisch für eine Divide-Operation ist. Wenn jedoch auch noch andere Operationen über den Calculator-Dienst durchgeführt werden, kann ein einzelner benutzerdefinierter SOAP-Fehler den Client über alle Rechnerfehlerbedingungen informieren, einschließlich Divide. Das folgende Codebeispiel zeigt die Erstellung des benutzerdefinierten SOAP-Fehlers MathFault. Dieser Fehler kann Fehler für alle mathematischen Operationen melden, auch für Divide. Während die Klasse eine Operation (die Operation-Eigenschaft) und einen Wert angeben kann, der das Problem beschreibt (die ProblemType-Eigenschaft), müssen die Klasse und diese Eigenschaften serialisierbar sein, um per benutzerdefiniertem SOAP-Fehler an den Client übertragen zu werden. Aus diesem Grund werden die Attribute System.Runtime.Serialization.DataContractAttribute und System.Runtime.Serialization.DataMemberAttribute verwendet, um den Typ und seine Eigenschaften serialisierbar und so interoperabel wie möglich zu machen.

' Define a math fault data contract
<DataContract([Namespace]:="http://Microsoft.ServiceModel.Samples")> _
Public Class MathFault

    Private m_operation As String
    Private m_problemType As String

    <DataMember()> _
    Public Property Operation() As String

        Get

            Return m_operation

        End Get

        Set(ByVal value As String)

            m_operation = value

        End Set

    End Property

    <DataMember()> _
    Public Property ProblemType() As String

        Get

            Return m_problemType

        End Get

        Set(ByVal value As String)

            m_problemType = value

        End Set

    End Property

End Class

// Define a math fault data contract
[DataContract(Namespace="http://Microsoft.ServiceModel.Samples")]
public class MathFault
{    
    private string operation;
    private string problemType;

    [DataMember]
    public string Operation
    {
        get { return operation; }
        set { operation = value; }
    }

    [DataMember]        
    public string ProblemType
    {
        get { return problemType; }
        set { problemType = value; }
    }

}

Weitere Informationen über zum Sicherstellen der Serialisierbarkeit der Daten finden Sie unter Angeben von Datenübertragung in Dienstverträgen. Eine Liste der Serialisierungsunterstützung, die System.Runtime.Serialization.DataContractSerializer bereitstellt, finden Sie unter Vom Datenvertragsserialisierer unterstützte Typen.

Markieren von Operationen, um den Fehlervertrag einzurichten

Nachdem Sie eine serialisierbare Datenstruktur definiert haben, die als Teil eines benutzerdefinierten SOAP-Fehlers zurückgegeben wird, besteht der letzte Schritt darin, Ihren Operationsvertrag so zu kennzeichnen, dass er einen SOAP-Fehler dieses Typs auslöst. Verwenden Sie dazu das System.ServiceModel.FaultContractAttribute-Attribut, und übergeben Sie den Typ des benutzerdefinierten Datentyps, den Sie erstellt haben. Das folgende Codebeispiel zeigt, wie Sie das FaultContractAttribute-Attribut verwenden, um anzugeben, dass die Divide-Operation einen SOAP-Fehler vom Typ MathFault zurückgeben kann. Andere mathematische Operationen können jetzt auch angeben, dass sie einen MathFault zurückgeben können.

<OperationContract()> _
<FaultContract(GetType(MathFault))> _
Function Divide(ByVal n1 As Integer, ByVal n2 As Integer) As Integer

[OperationContract]
[FaultContract(typeof(MathFault))]
int Divide(int n1, int n2);

Eine Operation kann angeben, dass sie mehr als einen benutzerdefinierten Fehler zurückgibt, indem Sie diese mit mehr als einem FaultContractAttribute-Attribut versehen.

Der nächste Schritt, das Einrichten des Fehlervertrags in der Implementierung der Operation, ist im Thema Senden und Empfangen von Fehlern beschrieben.

Überlegungen zu SOAP, WSDL und zur Interoperabilität

Unter bestimmten Umständen, besonders bei der Zusammenarbeit mit anderen Plattformen, kann es wichtig sein, die Art und Weise der Anzeige eines Fehlers in einer SOAP-Meldung bzw. seine Beschreibung in WSDL-Metadaten zu steuern.

Das FaultContractAttribute-Attribut verfügt über eine Name-Eigenschaft, die die Steuerung des WSDL-Fehlerelementnamens ermöglicht, der in den Metadaten für diesen Fehler generiert wird.

Gemäß SOAP-Standard kann ein Fehler die Elemente Action, Code und Reason aufweisen. Die Action wird von der Action-Eigenschaft gesteuert. Die Code-Eigenschaft und die Reason-Eigenschaften sind Eigenschaften der System.ServiceModel.FaultException-Klasse, bei der es sich um die übergeordnete Klasse der generischen System.ServiceModel.FaultException handelt. Die Code-Eigenschaft enthält einen SubCode-Member.

Beim Zugreifen auf andere Elemente als Dienste, die Fehler generieren, gelten bestimmte Einschränkungen. WCF unterstützt nur Fehler mit Detailtypen, die das Schema beschreibt und die mit Datenverträgen kompatibel sind. Wie oben erwähnt, unterstützt WCF zum Beispiel keine Fehler, die in ihren Detailtypen XML-Attribute verwenden, und keine Fehler mit mehr als einem Element der obersten Ebene im Detailabschnitt.

Siehe auch

Aufgaben

Vorgehensweise: Deklarieren von Fehlern in Dienstverträgen
Vorgehensweise: Festlegen der ProtectionLevel-Eigenschaft

Verweis

FaultContractAttribute
DataContractAttribute
DataMemberAttribute

Konzepte

Angeben und Behandeln von Fehlern in Verträgen und Diensten
Senden und Empfangen von Fehlern
Grundlagen der Schutzebene
Angeben von Datenübertragung in Dienstverträgen