Partager via

Pannes

  • Article

Un message d’erreur est utilisé pour communiquer des informations d’erreur sur une défaillance au niveau d’un point de terminaison distant. Un message d’erreur est similaire à 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 WS_FAULT . Bien qu’une erreur ait un ensemble fixe de champs utilisés pour fournir des informations sur l’échec (comme le WS_FAULT_CODE qui identifie le type d’erreur et le WS_FAULT_REASON qui contient du texte décrivant l’erreur), il contient également un champ de détail qui peut être utilisé pour spécifier du contenu XML arbitraire relatif à l’erreur.

Génération d’erreurs dans un service

Un service envoie généralement 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 dans le 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’appels envoie l’erreur à l’aide des informations capturées dans 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’erreurs sont mappées aux erreurs tout en permettant 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 :

  • WS_FAULT_ERROR_PROPERTY_ACTION. Spécifie l’action à utiliser pour le message d’erreur. Si ce n’est pas spécifié, une action par défaut est fournie.
  • WS_FAULT_ERROR_PROPERTY_FAULT. Il contient la structure WS_FAULT qui est envoyée dans le corps du message d’erreur.
  • WS_FAULT_ERROR_PROPERTY_HEADER. Certaines erreurs incluent des en-têtes de message qui sont ajoutés au message d’erreur pour transmettre les échecs de traitement relatifs aux en-têtes du message de demande. Cette propriété peut être utilisée pour spécifier un WS_XML_BUFFER contenant un en-tête à ajouter au message d’erreur.

Toutes les chaînes d’erreur ajoutées à l’objet WS_ERROR sont utilisées comme texte dans l’erreur envoyée. Vous pouvez ajouter des chaînes d’erreur à l’objet error à l’aide de WsAddErrorString.

La fonction WsSetFaultErrorProperty peut être utilisée pour définir ces 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 envoie automatiquement les erreurs en utilisant les informations ci-dessus dans l’objet WS_ERROR. La propriété WS_SERVICE_PROPERTY_FAULT_DISCLOSURE peut être utilisée pour contrôler le détail de l’envoi d’une erreur.

Si vous travaillez au niveau de la couche de canal, les 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 WS_E_ENDPOINT_FAULT_RECEIVED est retournée. (Pour plus d’informations, consultez Valeurs de retour des services Web Windows.) 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 reçue :

Une erreur peut contenir du contenu XML supplémentaire arbitraire dans les détails 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 lorsque vous traitez directement le contenu du corps d’un message d’erreur.

Le contenu du corps d’un message d’erreur est représenté par la structure WS_FAULT standard, qui prend en charge la sérialisation intégrée.

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 du corps d’un 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, le WS_MESSAGE_PROPERTY_IS_FAULT peut être consulté. Cette propriété est définie selon que le premier élément du corps est un élément d’erreur pendant WsReadMessageStart ou WsReadEnvelopeStart.

Pour créer un WS_FAULT donné un WS_ERROR, utilisez la fonction WsCreateFaultFromError .

Les énumérations suivantes font partie d’erreurs :

Les fonctions suivantes font partie des erreurs :

Les structures suivantes font partie des erreurs :