Freigeben über

Fehler

  • Artikel

Eine Fehlermeldung wird verwendet, um Fehlerinformationen über einen Fehler an einem Remoteendpunkt zu kommunizieren. Eine Fehlermeldung ist wie jede andere Nachricht, mit der Ausnahme, dass das Format des Nachrichtentexts ein Standardformat aufweist. Fehler können sowohl von Infrastrukturprotokollen wie WS-Adressierung als auch von Anwendungsprotokollen höherer Ebene verwendet werden.

Überblick

Der Inhalt des Textkörpers einer Fehlermeldung wird in dieser API mithilfe der WS_FAULT Struktur dargestellt. Obwohl ein Fehler einen festen Satz von Feldern enthält, die verwendet werden, um Informationen über den Fehler bereitzustellen (z. B. die WS_FAULT_CODE, die den Fehlertyp identifiziert, und die WS_FAULT_REASON, die Text enthält, der den Fehler beschreibt), enthält es auch ein Detailfeld, das verwendet werden kann, um beliebige XML-Inhalte im Zusammenhang mit dem Fehler anzugeben.

Generieren von Fehlern in einem Dienst

Ein Dienst sendet in der Regel einen Fehler aufgrund eines Fehlers, der bei der Verarbeitung der Anforderung aufgetreten ist. Das von dieser API verwendete Modell besteht darin, dass der Code im Dienst, der auf den Verarbeitungsfehler stößt, die erforderlichen Fehlerinformationen im WS_ERROR-Objekt erfasst, und code auf einer höheren Ebene in der Aufrufkette sendet den Fehler tatsächlich mithilfe der auf der unteren Ebene erfassten Informationen. Mit diesem Schema kann der Code, der den Fehler sendet, so isoliert werden, wie Fehlersituationen Fehlern zugeordnet werden, während gleichzeitig umfangreiche Fehlerinformationen gesendet werden können.

Die folgenden Eigenschaften können mit WsSetFaultErrorProperty- verwendet werden, um Fehlerinformationen für ein WS_ERROR-Objekt zu erfassen:

  • WS_FAULT_ERROR_PROPERTY_ACTION. Dadurch wird die Aktion angegeben, die für die Fehlermeldung verwendet werden soll. Wenn dies nicht angegeben ist, wird eine Standardaktion angegeben.
  • WS_FAULT_ERROR_PROPERTY_FAULT. Dies enthält die WS_FAULT Struktur, die im Textkörper der Fehlermeldung gesendet wird.
  • WS_FAULT_ERROR_PROPERTY_HEADER. Einige Fehler sind Nachrichtenkopfzeilen, die der Fehlermeldung hinzugefügt werden, um Verarbeitungsfehler im Zusammenhang mit Kopfzeilen der Anforderungsnachricht zu vermitteln. Diese Eigenschaft kann verwendet werden, um eine WS_XML_BUFFER anzugeben, die eine Kopfzeile enthält, die der Fehlermeldung hinzugefügt werden soll.

Alle Fehlerzeichenfolgen, die dem WS_ERROR-Objekt hinzugefügt werden, werden als Text im gesendeten Fehler verwendet. Fehlerzeichenfolgen können dem Fehlerobjekt mithilfe WsAddErrorString-hinzugefügt werden.

Die WsSetFaultErrorProperty--Funktion kann verwendet werden, um diese Eigenschaften des WS_ERROR-Objekts festzulegen.

Verwenden Sie die WsSetFaultErrorDetail--Funktion, um die Details des im WS_ERROR-Objekt gespeicherten Fehlers festzulegen. Diese Funktion kann verwendet werden, um beliebigen XML-Inhalt dem Fehler zuzuordnen.

Der ServiceHost- sendet automatisch Fehler mithilfe der oben genannten Informationen im WS_ERROR-Objekt. Die WS_SERVICE_PROPERTY_FAULT_DISCLOSURE-Eigenschaft kann verwendet werden, um zu steuern, wie detailliert ein Fehler gesendet wird.

Wenn sie auf der Kanalebene arbeiten, können Fehler für ein WS_ERROR-Objekt mithilfe von WsSendFaultMessageForErrorgesendet werden.

Behandeln von Fehlern auf einem Client

Wenn ein Client beim Verwenden eines ServiceProxy- oder über WsRequestReply oder WsReceiveMessage-einen Fehler empfängt, wird der WS_E_ENDPOINT_FAULT_RECEIVED Fehler zurückgegeben. (Weitere Informationen finden Sie unter Rückgabewerte für Windows-Webdienste.) Diese Funktionen füllen auch das WS_ERROR Objekt auf, das dem Aufruf mit Informationen zum empfangenen Fehler bereitgestellt wird.

Die folgenden Eigenschaften eines WS_ERROR-Objekts können mithilfe WsGetFaultErrorProperty abgefragt werden, um Informationen zu einem empfangenen Fehler abzurufen:

Ein Fehler kann beliebige zusätzliche XML-Inhalte im Detail des Fehlers enthalten. Auf diese Kann mithilfe der WsGetFaultErrorDetail--Funktion zugegriffen werden.

Verwenden von Fehlern mit Nachrichten

Der folgende Abschnitt gilt für den direkten Umgang mit dem Inhalt des Textkörpers einer Fehlermeldung.

Der Inhalt des Textkörpers einer Fehlermeldung wird durch die Standardstruktur WS_FAULT dargestellt, die integrierte Unterstützung für die Serialisierung bietet.

Der folgende Code kann beispielsweise verwendet werden, um einen Fehler in einen Nachrichtentext zu schreiben:

HRESULT hr;
WS_ELEMENT_DESCRIPTION faultDescription = { NULL, WS_FAULT_TYPE, NULL, NULL };
WS_FAULT fault = { ... };
hr = WsWriteBody(message, &faultDescription, WS_WRITE_REQUIRED_VALUE, &fault, sizeof(fault), error);

Der folgende Code kann verwendet werden, um einen Fehler aus einem Nachrichtentext zu lesen:

HRESULT hr;
WS_ELEMENT_DESCRIPTION faultDescription = { NULL, WS_FAULT_TYPE, NULL, NULL };
WS_FAULT fault;
hr = WsReadBody(message, &faultDescription, WS_READ_REQUIRED_VALUE, &fault, sizeof(fault), error);

Um zu wissen, ob eine empfangene Nachricht ein Fehler ist oder nicht, kann die WS_MESSAGE_PROPERTY_IS_FAULT konsultiert werden. Diese Eigenschaft wird basierend darauf festgelegt, ob das erste Element im Textkörper während WsReadMessageStart oder WsReadEnvelopeStartein Fehlerelement ist.

Verwenden Sie die WsCreateFaultFromError-Funktion, um eine WS_FAULT einer WS_ERRORzu erstellen.

Die folgenden Enumerationen sind Teil von Fehlern:

Die folgenden Funktionen sind Teil von Fehlern:

Die folgenden Strukturen sind Teil von Fehlern: