Edit

Faults

  • Article

A fault message is used to communicate error information about a failure at a remote endpoint. A fault message is like any other message, except the format of the message body has a standard format. Faults can be used both by infrastructure protocols, such as WS-Addressing, and by higher-level application protocols.

Overview

The contents of the body of a fault message is represented in this API using the WS_FAULT structure. Although a fault has a fixed set of fields used to providing information about the failure (like the WS_FAULT_CODE that identifies the type of fault, and the WS_FAULT_REASON that contains text describing the fault), it also contains a detail field that can be used to specify arbitrary XML content relating to the fault.

Generating faults in a Service

A service will typically send a fault due to some error that was encountered while processing the request. The model used by this API is that the code in the service that encounters the processing error will capture the necessary fault information in the WS_ERROR object, and then code at a higher level in the call chain will actually send the fault using the information captured at the lower layer. This scheme allows the code that sends the fault to be insulated from how errors situations are mapped to faults while still allowing for rich fault information to be sent.

The following properties can be used with WsSetFaultErrorProperty to capture fault information for a WS_ERROR object:

  • WS_FAULT_ERROR_PROPERTY_ACTION. This specifies the action to use for the fault message. If this is not specified, then a default action is supplied.
  • WS_FAULT_ERROR_PROPERTY_FAULT. This contains the WS_FAULT structure that is sent in the body of the fault message.
  • WS_FAULT_ERROR_PROPERTY_HEADER. Some faults include message headers which are added to the fault message to convey processing failures relating to headers of the request message. This property can be used to specify a WS_XML_BUFFER containing a header to be added to the fault message.

Any error strings that are added to the WS_ERROR object are used as the text in the fault that is sent. Error strings can be added to the error object using WsAddErrorString.

The WsSetFaultErrorProperty function can be used to set these properties of the WS_ERROR object.

To set the detail of the fault stored in the WS_ERROR object, use the WsSetFaultErrorDetail function. This function can be used to associate arbitrary XML content with the fault.

The Service Host will automatically send faults by using the above information in the WS_ERROR object. The WS_SERVICE_PROPERTY_FAULT_DISCLOSURE property can be used to control how detailed of a fault will be sent.

If working at the channel layer, faults can be sent for a WS_ERROR object using WsSendFaultMessageForError.

Handling faults on a client

If a client receives a fault when using a Service Proxy or via WsRequestReply or WsReceiveMessage, the WS_E_ENDPOINT_FAULT_RECEIVED error will be returned. (For more information, see Windows Web Services Return Values.) These functions will also populate the WS_ERROR object supplied to the call with information about the received fault.

The following properties of an WS_ERROR object can be queried using WsGetFaultErrorProperty to obtain information about a fault that was received:

A fault may contain arbitrary additional XML content in the detail of the fault. This can be accessed using the use the WsGetFaultErrorDetail function.

Using faults with messages

The following section applies when dealing directly with the contents of the body of a fault message.

The contents of the body of a fault message is represented by the standard WS_FAULT structure, which has built-in support for serialization.

For example, the following code can be used to write a fault to a message body:

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

The following code can be used to read a fault from a message body:

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

In order to know whether a received message is a fault or not, the WS_MESSAGE_PROPERTY_IS_FAULT can be consulted. This property is set based on whether the first element in the body is a fault element during WsReadMessageStart or WsReadEnvelopeStart.

To create a WS_FAULT given a WS_ERROR, use the WsCreateFaultFromError function.

The following enumerations are part of faults:

The following functions are part of faults:

The following structures are part of faults: