Fehler
Eine Fehlermeldung wird verwendet, um Fehlerinformationen zu einem 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 übergeordneten Anwendungsprotokollen verwendet werden.
- Übersicht
- Generieren von Fehlern in einem Dienst
- Behandeln von Fehlern auf einem Client
- Verwenden von Fehlern mit Nachrichten
Übersicht
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 zum Bereitstellen von Informationen über den Fehler verwendet werden (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 er auch ein Detailfeld, das verwendet werden kann, um beliebige XML-Inhalte in Bezug auf den 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 dann Code auf einer höheren Ebene in der Aufrufkette den Fehler mithilfe der auf der unteren Ebene erfassten Informationen sendet. Mit diesem Schema kann der Code, der den Fehler sendet, von der Zuordnung von Fehlersituationen zu Fehlern isoliert werden, während dennoch 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. Dies gibt die Aktion an, die für die Fehlermeldung verwendet werden soll. Wenn dies nicht angegeben ist, wird eine Standardaktion bereitgestellt.
- 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 umfassen Nachrichtenheader, die der Fehlermeldung hinzugefügt werden, um Verarbeitungsfehler in Bezug auf Header der Anforderungsnachricht zu übermitteln. Diese Eigenschaft kann verwendet werden, um einen WS_XML_BUFFER anzugeben, der einen Header enthält, der 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 von 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 -Objekts gespeicherten Fehlers festzulegen. Diese Funktion kann verwendet werden, um dem Fehler beliebige XML-Inhalte zuzuordnen.
Der Diensthost sendet Automatisch Fehler, indem er die oben genannten Informationen im WS_ERROR-Objekt verwendet. 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 WsSendFaultMessageForError gesendet werden.
Behandeln von Fehlern auf einem Client
Wenn ein Client bei Verwendung eines Dienstproxys 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 , das für den Aufruf bereitgestellt wird, mit Informationen über den empfangenen Fehler auf.
Die folgenden Eigenschaften eines WS_ERROR-Objekts können mithilfe von WsGetFaultErrorProperty abgefragt werden, um Informationen zu einem empfangenen Fehler abzurufen:
- WS_FAULT_ERROR_PROPERTY_ACTION. Dadurch wird der Aktionswert der Fehlermeldung angegeben.
- WS_FAULT_ERROR_PROPERTY_FAULT. Dies enthält die WS_FAULT Struktur, die aus dem Textkörper der Fehlernachricht deserialisiert wurde.
Ein Fehler kann beliebige zusätzliche XML-Inhalte im Detail des Fehlers enthalten. Darauf kann mithilfe der WsGetFaultErrorDetail-Funktion zugegriffen werden.
Verwenden von Fehlern mit Nachrichten
Der folgende Abschnitt gilt, wenn der Inhalt des Textkörpers einer Fehlermeldung direkt behandelt wird.
Der Inhalt des Textkörpers einer Fehlermeldung wird durch die Standardstruktur WS_FAULT dargestellt, die über integrierte Unterstützung für die Serialisierung verfügt.
Beispielsweise kann der folgende Code 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 der WS_MESSAGE_PROPERTY_IS_FAULT konsultiert werden. Diese Eigenschaft wird basierend darauf festgelegt, ob das erste Element im Textkörper ein Fehlerelement während WsReadMessageStart oder WsReadEnvelopeStart ist.
Verwenden Sie die Funktion WsCreateFaultFromError, um eine WS_FAULT zu erstellen, die einem WS_ERROR zugewiesen wird.
Die folgenden Enumerationen sind Teil von Fehlern:
Die folgenden Funktionen sind Teil von Fehlern:
- WsCreateFaultFromError
- WsGetFaultErrorDetail
- WsGetFaultErrorProperty
- WsSetFaultErrorDetail
- WsSetFaultErrorProperty
Die folgenden Strukturen sind Teil von Fehlern: