Condividi tramite

Errori

  • Articolo

Un messaggio di errore viene usato per comunicare informazioni sugli errori relativi a un 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 di applicazione di livello superiore.

Panoramica

Il contenuto del corpo di un messaggio di errore viene rappresentato in questa API usando la struttura WS_FAULT . Anche se un errore ha un set fisso di campi usati per fornire informazioni sull'errore (ad esempio la WS_FAULT_CODE che identifica il tipo di errore e la WS_FAULT_REASON che contiene il testo che descrive l'errore), contiene anche un campo 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 acquisisce 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 errori vengono mappate agli errori, consentendo comunque l'invio di informazioni di errore avanzate.

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

  • WS_FAULT_ERROR_PROPERTY_ACTION. In questo modo viene specificata l'azione da usare 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 aggiunte al messaggio di errore per trasmettere errori di elaborazione relativi alle intestazioni del messaggio di richiesta. Questa proprietà può essere usata 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 usate come testo nell'errore inviato. È possibile aggiungere stringhe di errore all'oggetto error usando WsAddErrorString.

La funzione WsSetFaultErrorProperty può essere usata per impostare queste proprietà dell'oggetto WS_ERROR .

Per impostare il dettaglio dell'errore archiviato nell'oggetto WS_ERROR , usare la funzione WsSetFaultErrorDetail . Questa funzione può essere usata 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 usata per controllare il modo in cui verrà inviato un errore dettagliato.

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 di servizio o tramite WsRequestReply o WsReceiveMessage, verrà restituito l'errore WS_E_ENDPOINT_FAULT_RECEIVED . Per altre informazioni, vedere Valori restituiti di Servizi Web Windows. Queste funzioni popolano anche l'oggetto WS_ERROR fornito alla chiamata con informazioni sull'errore ricevuto.

Le proprietà seguenti di un oggetto WS_ERROR possono essere eseguite query tramite WsGetFaultErrorProperty per ottenere informazioni su un errore ricevuto:

Un errore può contenere contenuto XML aggiuntivo arbitrario nel dettaglio dell'errore. È possibile accedere usando la funzione WsGetFaultErrorDetail .

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 WS_FAULT standard, che ha 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 nel corpo sia un elemento di errore durante WsReadMessageStart o WsReadEnvelopeStart.

Per creare un WS_FAULT specificato 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: