Angeben und Behandeln von Fehlern in Verträgen und DienstenSpecifying and Handling Faults in Contracts and Services

Windows Communication Foundation (WCF)Windows Communication Foundation (WCF)-Anwendungen behandeln Fehler, indem sie verwaltete Ausnahmeobjekte SOAP-Fehlerobjekten und SOAP-Fehlerobjekte verwalteten Ausnahmeobjekten zuordnen. applications handle error situations by mapping managed exception objects to SOAP fault objects and SOAP fault objects to managed exception objects. Die Themen in diesem Abschnitt erläutern, wie Verträge erstellt werden, die Fehlerbedingungen als benutzerdefinierte SOAP-Fehler verfügbar machen, wie solche Fehler als Teil einer Dienstimplementierung zurückgegeben werden, und wie Clients diese Fehler abfangen.The topics in this section discuss how to design contracts to expose error conditions as custom SOAP faults, how to return such faults as part of service implementation, and how clients catch such faults.

Übersicht über die FehlerbehandlungError Handling Overview

In allen verwalteten Anwendungen werden Verarbeitungsfehler durch Exception-Objekte dargestellt.In all managed applications, processing errors are represented by Exception objects. In SOAP-basierten Anwendungen, wie z. B. WCFWCF-Anwendungen, übermitteln Dienstmethoden Verarbeitungsfehlerinformationen mit SOAP-Fehlernachrichten.In SOAP-based applications such as WCFWCF applications, service methods communicate processing error information using SOAP fault messages. SOAP-Fehler sind Nachrichtentypen, die in den Metadaten für einen Dienstvorgang enthalten sind und daher einen Fehlervertrag erstellen, den Clients nutzen können, um ihre Ausführung robuster oder interaktiver zu gestalten.SOAP faults are message types that are included in the metadata for a service operation and therefore create a fault contract that clients can use to make their operation more robust or interactive. Da darüber hinaus SOAP-Fehler gegenüber Clients in XML-Form ausgedrückt werden, sind sie ein sehr interoperables Typsystem, das Clients auf jeder SOAP-Plattform verwenden können, wodurch sich die Reichweite Ihrer WCFWCF-Anwendung erhöht.In addition, because SOAP faults are expressed to clients in XML form, it is a highly interoperable type system that clients on any SOAP platform can use, increasing the reach of your WCFWCF application.

Da WCFWCF-Anwendungen unter beiden Fehlersystemtypen ausgeführt werden, müssen alle an den Client zu sendenden verwalteten Ausnahmeinformationen vom Dienst von Ausnahmen in SOAP-Fehler konvertiert, gesendet und von WCFWCF-Clients von SOAP-Fehlern in Ausnahmen konvertiert werden.Because WCFWCF applications run under both types of error systems, any managed exception information that is sent to the client must be converted from exceptions into SOAP faults on the service, sent, and converted from SOAP faults to fault exceptions in WCFWCF clients. Im Fall von Duplexclients können Clientverträge SOAP-Fehler auch zurück an einen Dienst senden.In the case of duplex clients, client contracts can also send SOAP faults back to a service. In beiden Fällen können Sie die Standard-Dienstausnahmeverhalten verwenden oder aber ausdrücklich steuern, ob und wie Ausnahmen Fehlernachrichten zugeordnet werden.In either case, you can use the default service exception behaviors, or you can explicitly control whether—and how—exceptions are mapped to fault messages.

Zwei Typen von SOAP-Fehler gesendet werden können: deklariert und nicht deklarierte.Two types of SOAP faults can be sent: declared and undeclared. Deklarierte SOAP-Fehler sind jene, bei denen ein Vorgang über ein System.ServiceModel.FaultContractAttribute-Attribut verfügt, das einen benutzerdefinierten SOAP-Fehlertyp angibt.Declared SOAP faults are those in which an operation has a System.ServiceModel.FaultContractAttribute attribute that specifies a custom SOAP fault type. Nicht deklarierte SOAP-Fehler sind nicht im Vertrag für einen Vorgang angegeben.Undeclared SOAP faults are not specified in the contract for an operation.

Es wird dringend empfohlen, dass Dienstvorgänge ihre Fehler mithilfe des FaultContractAttribute-Attributs deklarieren, um alle SOAP-Fehler formal anzugeben, die bei einem Client während des normalen Betriebs eingehen können.It is strongly recommended that service operations declare their faults by using the FaultContractAttribute attribute to formally specify all SOAP faults that a client can expect to receive in the normal course of an operation. Es wird außerdem empfohlen, dass in einem SOAP-Fehler nur die Informationen zurückgegeben werden, die ein Client erhalten muss, um die Offenlegung von Informationen möglichst gering zu halten.It is also recommended that you return in a SOAP fault only the information that a client must know to minimize information disclosure.

In der Regel führen Dienste (und Duplexclients) die folgenden Schritte aus, um die Fehlerbehandlung erfolgreich in ihre Anwendungen zu integrieren:Typically, services (and duplex clients) take the following steps to successfully integrate error handling into their applications:

  • Sie ordnen Ausnahmebedingungen benutzerdefinierten SOAP-Fehlern zu.Map exception conditions to custom SOAP faults.

  • Clients und Dienste senden und empfangen SOAP-Fehler als Ausnahmen.Clients and services send and receive SOAP faults as exceptions.

Zusätzlich können WCFWCF-Clients und -Dienste undeklarierte SOAP-Fehler zu Debuggingzwecken verwenden und können ihr standardmäßiges Fehlerverhalten erweitern.In addition, WCFWCF clients and services can use undeclared soap faults for debugging purposes and can extend the default error behavior. Diese Aufgaben und Begriffe werden in den folgenden Abschnitten erläutert.The following sections discuss these tasks and concepts.

Zuordnen von Ausnahmen zu SOAP-FehlernMap Exceptions to SOAP Faults

Der erste Schritt bei der Definition eines Verfahrens zur Behandlung von Fehlerbedingungen besteht darin zu entscheiden, unter welchen Bedingungen eine Clientanwendung über Fehler informiert werden sollte.The first step in creating an operation that handles error conditions is to decide under what conditions a client application should be informed about errors. Die Fehlerbedingungen mancher Vorgänge werden von ihrer Funktionalität bestimmt.Some operations have error conditions specific to their functionality. Ein PurchaseOrder-Vorgang könnte z. B. bestimmte Informationen an Kunden zurückgeben, denen es nicht mehr erlaubt ist, eine Bestellung zu tätigen.For example, a PurchaseOrder operation might return specific information to customers who are no longer permitted to initiate a purchase order. In anderen Fällen, etwa einem Calculator-Dienst, könnte ein allgemeinerer MathFault-SOAP-Fehler ausreichen, um alle Fehlerbedingungen für den gesamten Dienst zu beschreiben.In other cases, such as a Calculator service, a more general MathFault SOAP fault may be able to describe all error conditions across an entire service. Nachdem die Fehlerbedingungen der Clients Ihres Diensts identifiziert wurden, kann ein benutzerdefinierter SOAP-Fehler erstellt und der Vorgang dafür gekennzeichnet werden, dass er den SOAP-Fehler zurückgibt, wenn die entsprechende Fehlerbedingung eintritt.Once the error conditions of clients of your service are identified, a custom SOAP fault can be constructed and the operation can be marked as returning that SOAP fault when its corresponding error condition arises.

Weitere Informationen finden Sie unterFor more information aboutDieser Schritt von dem Dienst oder Client entwickeln finden Sie unter definieren und Angeben von Fehlern. this step of developing your service or client, see Defining and Specifying Faults.

Clients und Dienste behandeln SOAP-Fehler als AusnahmenClients and Services Handle SOAP Faults as Exceptions

Die Identifizierung von Fehlerbedingungen bei Vorgängen, die Erstellung benutzerdefinierter SOAP-Fehler sowie die Markierung dieser Vorgänge für die Rückgabe solcher Fehler sind die ersten Schritte einer erfolgreichen Fehlerbehandlung in WCFWCF-Anwendungen.Identifying operation error conditions, defining custom SOAP faults, and marking those operations as returning those faults are the first steps in successful error handling in WCFWCF applications. Der nächste Schritt besteht darin, das Senden und Empfangen dieser Fehler korrekt zu implementieren.The next step is to properly implement the sending and receiving of these faults. In der Regel werden Fehler von Diensten gesendet, um ihre Clientanwendungen über Fehlerbedingungen zu informieren. Duplexclients können jedoch selbst auch SOAP-Fehler an Dienste senden.Typically services send faults to inform client applications about error conditions, but duplex clients can also send SOAP faults to services.

Weitere Informationen finden Sie unterFor more information, seeSenden und Empfangen von Fehlern. Sending and Receiving Faults.

Undeklarierte SOAP-Fehler und DebuggenUndeclared SOAP Faults and Debugging

Deklarierte SOAP-Fehler sind äußerst nützlich zur Erstellung interoperabler, verteilter Anwendungen.Declared SOAP faults are extremely useful for building robust, interoperable, distributed applications. In manchen Fällen ist es jedoch für einen Dienst (oder einen Duplexclient) nützlich, einen undeklarierten SOAP-Fehler zu senden, also einen, der in der Web Services Description Language (WSDL) für diesen Vorgang nicht erwähnt ist.However, in some cases it is useful for a service (or duplex client) to send an undeclared SOAP fault, one that is not mentioned in the Web Services Description Language (WSDL) for that operation. Bei der Entwicklung eines Diensts können beispielsweise unerwartete Situationen eintreten, in denen es für Debuggingzwecke sinnvoll sein kann, Information an den Client zurückzusenden.For example, when developing a service, unexpected situations can occur in which it is useful for debugging purposes to send information back to the client. Zusätzlich können Sie die ServiceBehaviorAttribute.IncludeExceptionDetailInFaults-Eigenschaft oder die ServiceDebugBehavior.IncludeExceptionDetailInFaults-Eigenschaft auf true festlegen, um WCFWCF-Clients zu ermöglichen, Informationen über interne Dienstvorgangsausnahmen abzurufen.In addition, you can set the ServiceBehaviorAttribute.IncludeExceptionDetailInFaults property or the ServiceDebugBehavior.IncludeExceptionDetailInFaults property to true to permit WCFWCF clients to obtain information about internal service operation exceptions. Senden von Fehlern einzelner sowohl die Debugeigenschaften Verhalten festlegen, werden beschrieben senden und Empfangen von Fehlern.Both sending individual faults and setting the debugging behavior properties are described in Sending and Receiving Faults.

Wichtig

Da mit verwalteten Ausnahmen interne Anwendungsinformationen verfügbar gemacht werden können, kann mit der Festlegung von ServiceBehaviorAttribute.IncludeExceptionDetailInFaults oder ServiceDebugBehavior.IncludeExceptionDetailInFaults auf trueWCFWCF-Clients ermöglicht werden, Informationen über interne Dienstvorgangsausnahmen, einschließlich persönlich identifizierbarer oder anderer vertraulicher Informationen abzurufen.Because managed exceptions can expose internal application information, setting ServiceBehaviorAttribute.IncludeExceptionDetailInFaults or ServiceDebugBehavior.IncludeExceptionDetailInFaults to true can permit WCFWCF clients to obtain information about internal service operation exceptions, including personally identifiable or other sensitive information.

Daher wird die Festlegung von ServiceBehaviorAttribute.IncludeExceptionDetailInFaults oder ServiceDebugBehavior.IncludeExceptionDetailInFaults auf true nur für das vorübergehende Debuggen einer Dienstanwendung empfohlen.Therefore, setting ServiceBehaviorAttribute.IncludeExceptionDetailInFaults or ServiceDebugBehavior.IncludeExceptionDetailInFaults to true is recommended only as a way to temporarily debug a service application. Außerdem beinhaltet die WSDL für eine Methode, die nicht behandelte verwaltete Ausnahmen auf diese Weise zurückgibt, keinen Vertrag für die FaultException<TDetail> vom Typ ExceptionDetail.In addition, the WSDL for a method that returns unhandled managed exceptions in this way does not contain the contract for the FaultException<TDetail> of type ExceptionDetail. Clients müssen auf die Möglichkeit von unbekannten SOAP-Fehlern vorbereitet sein, die an WCFWCF-Clients als System.ServiceModel.FaultException-Objekte zurückgegeben werden, damit sie die Debuginformationen korrekt abrufen können.Clients must expect the possibility of an unknown SOAP fault (returned to WCFWCF clients as System.ServiceModel.FaultException objects) to obtain the debugging information properly.

Anpassen der Fehlerbehandlung mit IErrorHandlerCustomizing Error Handling with IErrorHandler

Wenn Sie spezielle Anforderungen bei der Anpassung der Antwortnachricht für den Client im Fall einer Ausnahme auf Anwendungsebene erfüllen oder spezielle Verarbeitungsschritte ausführen müssen, nachdem eine Antwortnachricht zurückgegeben wurde, dann implementieren Sie die System.ServiceModel.Dispatcher.IErrorHandler-Schnittstelle.If you have special requirements to either customize the response message to the client when an application-level exception happens or perform some custom processing after the response message is returned, implement the System.ServiceModel.Dispatcher.IErrorHandler interface.

Probleme bei der FehlerserialisierungFault Serialization Issues

Beim Deserialisieren eines Fehlervertrags versucht WCF zunächst, den Namen des Fehlervertrags in der SOAP-Nachricht einem Fehlervertragstyp zuzuordnen.When deserializing a fault contract, WCF first attempts to match the fault contract name in the SOAP message with the fault contract type. Wenn keine exakte Übereinstimmung gefunden werden kann, wird die Liste der verfügbaren Fehlerverträge in alphabetischer Reihenfolge nach einem kompatiblen Typ durchsucht.If it cannot find an exact match it will then search the list of available fault contracts in alphabetical order for a compatible type. Wenn zwei Fehlerverträge kompatible Typen darstellen (beispielsweise ist einer die Unterklasse eines anderen), wird möglicherweise der falsche Typ zum Deserialisieren des Fehlers verwendet.If two fault contracts are compatible types (one is a subclass of another, for example) the wrong type may be used to de-serialize the fault. Dies geschieht nur, wenn im Fehlervertrag nicht sowohl Name, als auch Namespace und Aktion angegeben wurden.This only occurs if the fault contract does not specify a name, namespace, and action. Um dieses Problem zu vermeiden, sollten Fehlerverträge daher stets durch Angabe von Attributen für Name, Namespace und Aktion vollständig qualifiziert werden.To prevent this issue from occurring, always fully qualify fault contracts by specifying the name, namespace, and action attributes. Darüber hinaus muss bei verwandten Fehlerverträgen, die von einer freigegebenen Basisklasse abgeleitet wurden, sichergestellt werden, dass neue Member mit [DataMember(IsRequired=true)] gekennzeichnet werden.Additionally if you have defined a number of related fault contracts derived from a shared base class, make sure to mark any new members with [DataMember(IsRequired=true)]. Weitere Informationen über das IsRequired-Attribut finden Sie unter DataMemberAttribute.For more information on this IsRequired attribute see, DataMemberAttribute. Dadurch wird verhindert, dass ein kompatibler Typ als Basisklasse verwendet wird, und die Deserialisierung des Fehlers in den richtigen abgeleiteten Typ wird erzwungen.This will prevent a base class from being a compatible type and force the fault to be deserialized into the correct derived type.

Siehe auchSee Also

FaultException
FaultContractAttribute
FaultException
XmlSerializer
XmlSerializerFormatAttribute
FaultContractAttribute
CommunicationException
Action
Code
Reason
SubCode
IsOneWay
Definieren und Angeben von FehlernDefining and Specifying Faults