Training
Module
Work with web services in Dynamics 365 Business Central - Training
Use SOAP and OData to read and update records, and handle UI interaction in Business Central.
This browser is no longer supported.
Upgrade to Microsoft Edge to take advantage of the latest features, security updates, and technical support.
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.
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.
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:
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.
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.
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:
Training
Module
Work with web services in Dynamics 365 Business Central - Training
Use SOAP and OData to read and update records, and handle UI interaction in Business Central.