Partager via

Défauts

  • Article

Un message d’erreur est utilisé pour communiquer des informations d’erreur sur un échec sur un point de terminaison distant. Un message d’erreur est similaire à n’importe quel 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.

Aperçu

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 l'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 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’appels envoie réellement l’erreur à l’aide des informations capturées au niveau inférieur. 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 autorisant l’envoi d’informations d’erreur enrichies.

Les propriétés suivantes peuvent être utilisées avec WsSetFaultErrorProperty pour capturer des informations d’erreur pour un objet WS_ERROR :

  • WS_FAULT_ERROR_PROPERTY_ACTION. Cela 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 envoyée dans le corps du message d’erreur.
  • WS_FAULT_ERROR_PROPERTY_HEADER. Certaines erreurs incluent les en-têtes de message ajoutés au message d’erreur pour transmettre les échecs de traitement liés aux en-têtes du message de requête. 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. Les 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 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 des erreurs à l’aide des informations ci-dessus dans l’objet WS_ERROR. La propriété WS_SERVICE_PROPERTY_FAULT_DISCLOSURE peut être utilisée pour contrôler la façon dont une erreur est envoyée.

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 de 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 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 directement au contenu du corps d’un message d’erreur.

Le contenu du corps d’un message d’erreur est représenté par la structure de 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 un corps de 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, 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 une WS_FAULT donnée à un WS_ERROR, 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 :