Condividi tramite

Vizio

  • Articolo

Un messaggio di errore viene usato per comunicare informazioni sull'errore in un endpoint remoto. Un messaggio di errore è simile a qualsiasi altro messaggio, ad eccezione del formato del corpo del messaggio ha un formato standard. Gli errori possono essere usati sia dai protocolli di infrastruttura, ad esempio WS-Addressing, sia da protocolli applicativi di livello superiore.

Panoramica

Il contenuto del corpo di un messaggio di errore è rappresentato in questa API usando la struttura WS_FAULT. Anche se un errore ha un set fisso di campi utilizzati per fornire informazioni sull'errore (ad esempio il WS_FAULT_CODE che identifica il tipo di errore e la WS_FAULT_REASON che contiene testo che descrive l'errore), contiene anche un campo di dettaglio che può essere usato per specificare contenuto XML arbitrario relativo all'errore.

Generazione di errori in un servizio

Un servizio in genere invierà un errore a causa di un errore rilevato durante l'elaborazione della richiesta. Il modello usato da questa API è che il codice nel servizio che rileva l'errore di elaborazione acquisirà le informazioni di errore necessarie nell'oggetto WS_ERROR e quindi il codice a un livello superiore nella catena di chiamate invierà effettivamente l'errore usando le informazioni acquisite al livello inferiore. Questo schema consente al codice che invia l'errore di essere isolato dal modo in cui le situazioni di errore vengono mappate agli errori, consentendo comunque l'invio di informazioni di errore avanzate.

Le proprietà seguenti possono essere usate con WsSetFaultErrorProperty per acquisire informazioni sull'errore per un oggetto WS_ERROR:

  • WS_FAULT_ERROR_PROPERTY_ACTION. Specifica l'azione da utilizzare per il messaggio di errore. Se non viene specificato, viene fornita un'azione predefinita.
  • WS_FAULT_ERROR_PROPERTY_FAULT. Contiene la struttura WS_FAULT inviata nel corpo del messaggio di errore.
  • WS_FAULT_ERROR_PROPERTY_HEADER. Alcuni errori includono intestazioni di messaggio che vengono aggiunte al messaggio di errore per comunicare gli errori di elaborazione relativi alle intestazioni del messaggio di richiesta. Questa proprietà può essere utilizzata per specificare un WS_XML_BUFFER contenente un'intestazione da aggiungere al messaggio di errore.

Tutte le stringhe di errore aggiunte all'oggetto WS_ERROR vengono utilizzate come testo nell'errore inviato. È possibile aggiungere stringhe di errore all'oggetto errore usando WsAddErrorString.

La funzioneWsSetFaultErrorPropertypuò essere utilizzata per impostare queste proprietà dell'oggetto WS_ERROR.

Per impostare i dettagli dell'errore archiviato nell'oggetto WS_ERROR, utilizzare la funzioneWsSetFaultErrorDetail. Questa funzione può essere utilizzata per associare contenuto XML arbitrario all'errore.

L'host del servizio invierà automaticamente errori usando le informazioni precedenti nell'oggetto WS_ERROR. La proprietà WS_SERVICE_PROPERTY_FAULT_DISCLOSURE può essere utilizzata per controllare il modo in cui verrà inviato un errore in dettaglio.

Se si lavora a livello di canale, è possibile inviare errori per un oggetto WS_ERROR usando WsSendFaultMessageForError.

Gestione degli errori in un client

Se un client riceve un errore quando si usa un proxy del servizio di o tramite WsRequestReply o WsReceiveMessage, verrà restituito l'errore di WS_E_ENDPOINT_FAULT_RECEIVED. Per altre informazioni, vedere i valori restituiti di Servizi Web Windows.) Queste funzioni popolano anche l'oggetto WS_ERROR fornito alla chiamata con informazioni sull'errore ricevuto.

È possibile eseguire query sulle proprietà seguenti di un oggetto WS_ERROR usando WsGetFaultErrorProperty per ottenere informazioni su un errore ricevuto:

Un errore può contenere contenuto XML aggiuntivo arbitrario nel dettaglio dell'errore. È possibile accedervi usando la funzioneWsGetFaultErrorDetail.

Uso di errori con messaggi

La sezione seguente si applica quando si tratta direttamente del contenuto del corpo di un messaggio di errore.

Il contenuto del corpo di un messaggio di errore è rappresentato dalla struttura di WS_FAULT standard, che include il supporto predefinito per la serializzazione.

Ad esempio, il codice seguente può essere usato per scrivere un errore in un corpo del messaggio:

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

Il codice seguente può essere usato per leggere un errore da un corpo del messaggio:

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

Per sapere se un messaggio ricevuto è un errore o meno, è possibile consultare il WS_MESSAGE_PROPERTY_IS_FAULT. Questa proprietà viene impostata in base al fatto che il primo elemento del corpo sia un elemento di errore durante WsReadMessageStart o WsReadEnvelopeStart.

Per creare un WS_FAULT dato un WS_ERROR, usare la funzione WsCreateFaultFromError.

Le enumerazioni seguenti fanno parte degli errori:

Le funzioni seguenti fanno parte degli errori:

Le strutture seguenti fanno parte degli errori: