Pannes

Un message d’erreur est utilisé pour communiquer les informations d’erreur relatives à un échec au niveau d’un point de terminaison distant. Un message d’erreur est semblable à tout autre message, sauf que le format du corps du message a un format standard. Les erreurs peuvent être utilisées à la fois par les protocoles d’infrastructure, tels que WS-Addressing et par les protocoles d’application de niveau supérieur.

Vue d’ensemble

Le contenu du corps d’un message d’erreur est représenté dans cette API à l’aide de la structure d' _ erreur WS . Bien qu’une erreur ait un ensemble fixe de champs utilisés pour fournir des informations sur l’échec (par exemple, le _ _ code d’erreur WS qui identifie le type d’erreur et la raison de l' _ erreur _ WS qui contient le texte décrivant l’erreur), elle contient également un champ de détail qui peut être utilisé pour spécifier le contenu XML arbitraire relatif à l’erreur.

Génération d’erreurs dans un service

En général, un service envoie une erreur en raison d’une erreur rencontrée lors du traitement de la demande. Le modèle utilisé par cette API est que le code du service qui rencontre l’erreur de traitement capture les informations d’erreur nécessaires dans l’objet WS _ Error , puis le code à un niveau supérieur dans la chaîne d’appel envoie en fait l’erreur à l’aide des informations capturées au niveau de la couche inférieure. Ce schéma permet au code qui envoie l’erreur d’être isolé de la façon dont les situations d’erreur sont mappées à des erreurs, tout en autorisant l’envoi d’informations d’erreur enrichies.

Les propriétés suivantes peuvent être utilisées avec WsSetFaultErrorProperty pour capturer les informations d’erreur d’un objet WS _ Error :

Toutes les chaînes d’erreur ajoutées à l’objet WS _ Error sont utilisées comme texte dans l’erreur envoyée. Des chaînes d’erreur peuvent être ajoutées à l’objet d’erreur à l’aide de WsAddErrorString.

La fonction WsSetFaultErrorProperty peut être utilisée pour définir les propriétés de l’objet WS _ Error .

Pour définir les détails de l’erreur stockée dans l’objet WS _ Error , utilisez la fonction WsSetFaultErrorDetail . Cette fonction peut être utilisée pour associer du contenu XML arbitraire à l’erreur.

L' hôte de service enverra automatiquement des erreurs en utilisant les informations ci-dessus dans l’objet WS _ Error . La propriété de Divulgation d’erreur de _ propriété de service _ _ _ Web peut être utilisée pour contrôler la façon dont l’erreur est envoyée.

Si vous travaillez au niveau de la couche de canal, des erreurs peuvent être envoyées pour un objet WS _ Error à l’aide de WsSendFaultMessageForError.

Gestion des erreurs sur un client

Si un client reçoit une erreur lors de l’utilisation d’un proxy de service ou via WsRequestReply ou WsReceiveMessage, l’erreur de point de terminaison WS _ E _ _ _ received est retournée. (pour plus d’informations, consultez Windows les valeurs de retour des Services Web.) Ces fonctions remplissent également l’objet WS _ Error fourni à l’appel avec des informations sur l’erreur reçue.

Les propriétés suivantes d’un objet WS _ Error peuvent être interrogées à l’aide de WsGetFaultErrorProperty pour obtenir des informations sur une erreur qui a été reçue :

Une erreur peut contenir du contenu XML supplémentaire arbitraire dans le détail de l’erreur. Vous pouvez y accéder à l’aide de la fonction WsGetFaultErrorDetail .

Utilisation d’erreurs avec des messages

La section suivante s’applique lors de la gestion directe du contenu du corps d’un message d’erreur.

Le contenu du corps d’un message d’erreur est représenté par la structure de l' _ erreur WS standard, qui dispose d’une prise en charge intégrée pour la sérialisation.

Par exemple, le code suivant peut être utilisé pour écrire une erreur dans le corps d’un message :

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);

Le code suivant peut être utilisé pour lire une erreur à partir d’un corps de message :

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);

Pour savoir si un message reçu est une erreur ou non, la propriété du _ message WS _ est _ l' _ erreur peut être consultée. Cette propriété est définie selon que le premier élément du corps est un élément Fault pendant WsReadMessageStart ou WsReadEnvelopeStart.

Pour créer une erreur WS _ en raison d’une _ erreur WS, utilisez la fonction WsCreateFaultFromError .

Les énumérations suivantes font partie des erreurs :

Les fonctions suivantes font partie des erreurs :

Les structures suivantes font partie des erreurs :