通过

错误

  • 项目

错误消息用于传达有关远程终结点故障的错误信息。 错误消息与其他任何消息类似，但消息正文的格式具有标准格式。 故障可以由基础结构协议（如 WS 寻址）和更高级别的应用程序协议使用。

概述

此 API 使用 WS_FAULT 结构表示错误消息正文的内容。 尽管故障具有一组固定字段，用于提供有关故障 (的信息，例如标识故障类型的 WS_FAULT_CODE ，以及包含描述故障) 文本的 WS_FAULT_REASON ，但它还包含可用于指定与错误相关的任意 XML 内容的详细信息字段。

在服务中生成故障

由于处理请求时遇到某些错误，服务通常会发送错误。 此 API 使用的模型是，服务中遇到处理错误的代码将在 WS_ERROR 对象中捕获必要的错误信息，然后调用链中更高级别的代码实际上将使用在下层捕获的信息发送错误。 此方案允许发送故障的代码与将错误情况映射到故障的方式隔离开来，同时仍允许发送丰富的故障信息。

以下属性可用于 WsSetFaultErrorProperty ，以捕获 WS_ERROR 对象的错误信息：

添加到 WS_ERROR 对象的任何错误字符串都用作发送的错误中的文本。 可以使用 WsAddErrorString 将错误字符串添加到错误对象。

WsSetFaultErrorProperty 函数可用于设置WS_ERROR对象的这些属性。

若要设置 存储在 WS_ERROR 对象中的错误的详细信息，请使用 WsSetFaultErrorDetail 函数。 此函数可用于将任意 XML 内容与错误相关联。

服务主机将使用 WS_ERROR 对象中的上述信息自动发送错误。 WS_SERVICE_PROPERTY_FAULT_DISCLOSURE 属性可用于控制错误的详细发送方式。

如果在通道层工作，则可以使用 WsSendFaultMessageForError 为WS_ERROR对象发送故障。

处理客户端上的错误

如果客户端在使用 服务代理 时或通过 WsRequestReply 或 WsReceiveMessage 收到错误，则将返回 WS_E_ENDPOINT_FAULT_RECEIVED 错误。 (有关详细信息，请参阅 Windows Web Services 返回值。) 这些函数还将使用有关收到的错误的信息填充提供给调用的 WS_ERROR 对象。

可以使用 WsGetFaultErrorProperty 查询WS_ERROR 对象的以下属性，以获取有关收到的错误的信息：

错误的详细信息中可能包含任意的附加 XML 内容。 可以使用 WsGetFaultErrorDetail 函数来访问。

对消息使用错误

以下部分适用于直接处理错误消息正文的内容时。

错误消息正文的内容由标准 WS_FAULT 结构表示，该结构具有对序列化的内置支持。

例如，以下代码可用于将错误写入消息正文：

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

以下代码可用于从消息正文中读取错误：

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

若要了解收到的消息是否为错误，可以查阅 WS_MESSAGE_PROPERTY_IS_FAULT 。 此属性的设置基于正文中的第一个元素是 WsReadMessageStart 还是 WsReadEnvelopeStart 期间的容错元素。

若要在 给定WS_ERROR 的情况下创建 WS_FAULT，请使用 WsCreateFaultFromError 函数。

以下枚举是错误的一部分：

以下函数是错误的一部分：

以下结构是故障的一部分：