Definieren und Angeben von FehlernDefining and Specifying Faults

SOAP-Fehler vermitteln Informationen zu Fehlerbedingungen auf interoperable Weise von einem Dienst an einen Client und bei Duplexkommunikation von einem Client an einen Dienst.SOAP faults convey error condition information from a service to a client and, in the duplex case, from a client to a service in an interoperable way. In diesem Thema wird beschrieben, wann und wie Sie benutzerdefinierten Fehlerinhalt definieren und wie Sie angeben, welche Vorgänge diesen zurückgeben können.This topic discusses when and how to define custom fault content and specify which operations can return them. Weitere Informationen finden Sie unterFor more information aboutein Dienst oder ein duplexclient, senden kann, diese Fehler und wie eine Client- oder dienstanwendung diese Fehler behandelt werden, finden Sie unter senden und Empfangen von Fehlern. how a service, or duplex client, can send those faults and how a client or service application handles these faults, see Sending and Receiving Faults. Einen Überblick über die Fehlerbehandlung in Windows Communication Foundation (WCF)Windows Communication Foundation (WCF) -Anwendungen finden Sie unter angeben und Behandeln von Fehlern in Verträgen und Diensten.For an overview of error handling in Windows Communication Foundation (WCF)Windows Communication Foundation (WCF) applications, see Specifying and Handling Faults in Contracts and Services.

ÜbersichtOverview

Bei deklarierten SOAP-Fehlern verfügt ein Vorgang über ein System.ServiceModel.FaultContractAttribute, das einen benutzerdefinierten SOAP-Fehlertyp angibt.Declared SOAP faults are those in which an operation has a System.ServiceModel.FaultContractAttribute that specifies a custom SOAP fault type. Nicht deklarierte SOAP-Fehler sind Fehler, die nicht im Vertrag eines Vorgangs festgelegt sind.Undeclared SOAP faults are those that are not specified in the contract for an operation. 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.This topic helps you identify those error conditions and create a fault contract for your service that clients can use to properly handle those error conditions when notified by custom SOAP faults. Die folgenden grundlegenden Aufgaben gelten in dieser Reihenfolge:The basic tasks are, in order:

  1. Definieren Sie die Fehlerbedingungen, über die ein Client Ihres Dienstes informiert werden sollte.Define the error conditions that a client of your service should know about.

  2. Definieren Sie für diese Fehlerbedingungen den benutzerdefinierten Inhalt der SOAP-Fehler.Define the custom content of the SOAP faults for those error conditions.

  3. Kennzeichnen Sie Ihre Vorgänge, damit die spezifischen SOAP-Fehler, die diese Vorgänge auslösen, für Clients in WSDL offengelegt werden.Mark your operations so that the specific SOAP faults that they throw are exposed to clients in WSDL.

Definieren von Fehlerbedingungen, über die Clients informiert werden sollenDefining Error Conditions That Clients Should Know About

SOAP-Fehler sind öffentlich beschriebene Meldungen, die Fehlerinformationen für einen besonderen Vorgang enthalten.SOAP faults are publicly described messages that carry fault information for a particular operation. 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.Because they are described along with other operation messages in WSDL, clients know and, therefore, expect to handle such faults when invoking an operation. Da WCFWCF-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.But because WCFWCF services are written in managed code, deciding which error conditions in managed code are to be converted into faults and returned to the client provides you the opportunity to separate error conditions and bugs in your service from the formal error conversation you have with a client.

Das folgende Codebeispiel zeigt zum Beispiel einen Vorgang, bei dem zwei ganze Zahlen verwendet und eine weitere ganze Zahl zurückgegeben wird.For example, the following code example shows an operation that takes two integers and returns another integer. 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.Several exceptions can be thrown here, so when designing the fault contract, you must determine which error conditions are important for your client. In diesem Fall muss der Dienst die System.DivideByZeroException-Ausnahme erkennen.In this case, the service should detect the System.DivideByZeroException exception.

[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.In the preceding example the operation can either return a custom SOAP fault that is specific to dividing by zero, a custom fault that is specific to math operations but that contains information specific to dividing by zero, multiple faults for several different error situations, or no SOAP fault at all.

Definieren des Inhalts von FehlerbedingungenDefine the Content of Error Conditions

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.Once an error condition has been identified as one that can usefully return a custom SOAP fault, the next step is to define the contents of that fault and ensure that the content structure can be serialized. 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.The code example in the preceding section shows an error specific to a Divide operation, but if there are other operations on the Calculator service, then a single custom SOAP fault can inform the client of all calculator error conditions, Divide included. 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.The following code example shows the creation of a custom SOAP fault, MathFault, which can report errors made using all math operations, including 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.While the class can specify an operation (the Operation property) and a value that describes the problem (the ProblemType property), the class and these properties must be serializable to be transferred to the client in a custom SOAP fault. 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.Therefore, the System.Runtime.Serialization.DataContractAttribute and System.Runtime.Serialization.DataMemberAttribute attributes are used to make the type and its properties serializable and as interoperable as possible.

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

}
' 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

Weitere Informationen finden Sie unterFor more information aboutGewusst wie: sicherzustellen, dass Ihre Daten serialisierbar ist, finden Sie unter angeben von Datenübertragung in Dienstverträgen. how to ensure your data is serializable, see Specifying Data Transfer in Service Contracts. Eine Liste der Serialisierung zu unterstützen, die System.Runtime.Serialization.DataContractSerializer bereitstellt, finden Sie unter Typen unterstützt, durch den Datenvertragsserialisierer.For a list of the serialization support that System.Runtime.Serialization.DataContractSerializer provides, see Types Supported by the Data Contract Serializer.

Markieren von Operationen, um den Fehlervertrag einzurichtenMark Operations to Establish the Fault Contract

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.Once a serializable data structure that is returned as part of a custom SOAP fault is defined, the last step is to mark your operation contract as throwing a SOAP fault of that type. Verwenden Sie dazu das System.ServiceModel.FaultContractAttribute-Attribut, und übergeben Sie den Typ des benutzerdefinierten Datentyps, den Sie erstellt haben.To do this, use the System.ServiceModel.FaultContractAttribute attribute and pass the type of the custom data type that you have constructed. 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.The following code example shows how to use the FaultContractAttribute attribute to specify that the Divide operation can return a SOAP fault of type MathFault. Andere mathematische Operationen können jetzt auch angeben, dass sie einen MathFault zurückgeben können.Other math-based operations can now also specify that they can return a MathFault.

[OperationContract]
[FaultContract(typeof(MathFault))]
int Divide(int n1, int n2);
<OperationContract()> _
<FaultContract(GetType(MathFault))> _
Function Divide(ByVal n1 As Integer, ByVal n2 As Integer) As Integer

Eine Operation kann angeben, dass sie mehr als einen benutzerdefinierten Fehler zurückgibt, indem Sie diese mit mehr als einem FaultContractAttribute-Attribut versehen.An operation can specify that it returns more than one custom fault by marking that operation with more than one FaultContractAttribute attribute.

Der nächste Schritt, zum Implementieren des fehlervertrags in Ihrer vorgangsimplementierung wird in diesem Thema beschriebenen senden und Empfangen von Fehlern.The next step, to implement the fault contract in your operation implementation, is described in the topic Sending and Receiving Faults.

Überlegungen zu SOAP, WSDL und zur InteroperabilitätSOAP, WSDL, and Interoperability Considerations

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.In some circumstances, especially when interoperating with other platforms, it may be important to control the way a fault appears in a SOAP message or the way it is described in the WSDL metadata.

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.The FaultContractAttribute attribute has a Name property that allows control of the WSDL fault element name that is generated in the metadata for that fault.

Gemäß SOAP-Standard kann ein Fehler die Elemente Action, Code und Reason aufweisen.According to the SOAP standard, a fault can have an Action, a Code, and a Reason. Die Action wird von der Action-Eigenschaft gesteuert.The Action is controlled by the Action property. 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<TDetail> handelt.The Code property and Reason property are both properties of the System.ServiceModel.FaultException class, which is the parent class of the generic System.ServiceModel.FaultException<TDetail>. Die Code-Eigenschaft enthält einen SubCode-Member.The Code property includes a SubCode member.

Beim Zugreifen auf andere Elemente als Dienste, die Fehler generieren, gelten bestimmte Einschränkungen.When accessing non-services that generate faults, certain limitations exist. WCFWCF unterstützt nur Fehler mit Detailtypen, die das Schema beschreibt und die mit Datenverträgen kompatibel sind. supports only faults with detail types that the schema describes and that are compatible with data contracts. Wie oben erwähnt, unterstützt WCFWCF zum Beispiel keine Fehler, die in ihren Detailtypen XML-Attribute verwenden, und keine Fehler mit mehr als einem Element der obersten Ebene im Detailabschnitt.For example, as mentioned above, WCFWCF does not support faults that use XML attributes in their detail types, or faults with more than one top-level element in the detail section.

Siehe auchSee Also

FaultContractAttribute
DataContractAttribute
DataMemberAttribute
Angeben und Behandeln von Fehlern in Verträgen und DienstenSpecifying and Handling Faults in Contracts and Services
Senden und Empfangen von FehlernSending and Receiving Faults
Vorgehensweise: Deklarieren von Fehlern in DienstverträgenHow to: Declare Faults in Service Contracts
Grundlagen der SchutzebeneUnderstanding Protection Level
Vorgehensweise: Festlegen der ProtectionLevel-EigenschaftHow to: Set the ProtectionLevel Property
Angeben von Datenübertragung in DienstverträgenSpecifying Data Transfer in Service Contracts