Delen via

Fouten

  • Artikel

Er wordt een foutbericht gebruikt om foutinformatie over een fout op een extern eindpunt te communiceren. Een foutbericht is net als elk ander bericht, behalve de indeling van de berichttekst heeft een standaardindeling. Fouten kunnen zowel worden gebruikt door infrastructuurprotocollen, zoals WS-Adressering, als door toepassingsprotocollen op een hoger niveau.

Overzicht

De inhoud van de hoofdtekst van een foutbericht wordt in deze API weergegeven met behulp van de WS_FAULT structuur. Hoewel een fout een vaste set velden bevat die worden gebruikt voor het verstrekken van informatie over de fout (zoals de WS_FAULT_CODE die het type fout aangeeft en de WS_FAULT_REASON die tekst bevat die de fout beschrijft), bevat het ook een detailveld dat kan worden gebruikt om willekeurige XML-inhoud met betrekking tot de fout op te geven.

Fouten genereren in een service

Een service verzendt doorgaans een fout vanwege een fout die is opgetreden tijdens het verwerken van de aanvraag. Het model dat door deze API wordt gebruikt, is dat de code in de service die de verwerkingsfout tegenkomt, de benodigde foutinformatie in het WS_ERROR-object vastlegt en vervolgens code op een hoger niveau in de aanroepketen de fout verzendt met behulp van de informatie die op de lagere laag is vastgelegd. Met dit schema kan de code die de fout verzendt worden geïsoleerd van de manier waarop foutensituaties worden toegewezen aan fouten, terwijl er nog steeds uitgebreide foutinformatie kan worden verzonden.

De volgende eigenschappen kunnen worden gebruikt met WsSetFaultErrorProperty- om foutinformatie voor een WS_ERROR-object vast te leggen:

  • WS_FAULT_ERROR_PROPERTY_ACTION. Hiermee geeft u de actie op die moet worden gebruikt voor het foutbericht. Als dit niet is opgegeven, wordt er een standaardactie opgegeven.
  • WS_FAULT_ERROR_PROPERTY_FAULT. Dit bevat de WS_FAULT structuur die wordt verzonden in de hoofdtekst van het foutbericht.
  • WS_FAULT_ERROR_PROPERTY_HEADER. Sommige fouten zijn berichtkoppen die worden toegevoegd aan het foutbericht om verwerkingsfouten met betrekking tot headers van het aanvraagbericht over te brengen. Deze eigenschap kan worden gebruikt om een WS_XML_BUFFER met een koptekst op te geven die aan het foutbericht moet worden toegevoegd.

Foutreeksen die aan het WS_ERROR-object worden toegevoegd, worden gebruikt als de tekst in de fout die wordt verzonden. Foutreeksen kunnen worden toegevoegd aan het foutobject met behulp van WsAddErrorString.

De functie WsSetFaultErrorProperty kan worden gebruikt om deze eigenschappen van het WS_ERROR-object in te stellen.

Gebruik de functie WsSetFaultErrorDetail om de details in te stellen van de fout die is opgeslagen in het WS_ERROR-object. Deze functie kan worden gebruikt om willekeurige XML-inhoud te koppelen aan de fout.

De -servicehost- verzendt automatisch fouten met behulp van de bovenstaande informatie in het WS_ERROR-object. De eigenschap WS_SERVICE_PROPERTY_FAULT_DISCLOSURE kan worden gebruikt om te bepalen hoe gedetailleerd een fout wordt verzonden.

Als u op de kanaallaag werkt, kunnen fouten worden verzonden voor een WS_ERROR-object met behulp van WsSendFaultMessageForError.

Fouten op een client afhandelen

Als een client een fout ontvangt bij het gebruik van een serviceproxy of via WsRequestReply of WsReceiveMessage, wordt de WS_E_ENDPOINT_FAULT_RECEIVED fout geretourneerd. (Zie voor meer informatie Windows Web Services Waarden retourneren.) Met deze functies wordt ook het WS_ERROR object ingevuld dat aan de aanroep is verstrekt met informatie over de ontvangen fout.

De volgende eigenschappen van een WS_ERROR-object kunnen worden opgevraagd met behulp van WsGetFaultErrorProperty om informatie te verkrijgen over een fout die is ontvangen:

Een fout kan willekeurige aanvullende XML-inhoud bevatten in de details van de fout. Dit kan worden geopend met behulp van de WsGetFaultErrorDetail functie.

Fouten gebruiken met berichten

De volgende sectie is van toepassing bij het rechtstreeks verwerken van de inhoud van de hoofdtekst van een foutbericht.

De inhoud van de hoofdtekst van een foutbericht wordt vertegenwoordigd door de standaardstructuur WS_FAULT, die ingebouwde ondersteuning biedt voor serialisatie.

De volgende code kan bijvoorbeeld worden gebruikt om een fout naar een berichttekst te schrijven:

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

De volgende code kan worden gebruikt om een fout uit een berichttekst te lezen:

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

Om te weten of een ontvangen bericht een fout is of niet, kan de WS_MESSAGE_PROPERTY_IS_FAULT worden geraadpleegd. Deze eigenschap wordt ingesteld op basis van of het eerste element in de hoofdtekst een foutelement is tijdens WsReadMessageStart of WsReadEnvelopeStart.

Als u een WS_FAULT wilt maken op basis van een WS_ERROR, gebruikt u de functie WsCreateFaultFromError.

De volgende opsommingen maken deel uit van fouten:

De volgende functies maken deel uit van fouten:

De volgende structuren maken deel uit van fouten: