共用方式為

故障

  • 發行項

錯誤訊息可用來傳達遠端端點失敗的相關錯誤資訊。 錯誤訊息就像任何其他訊息一樣，但訊息本文的格式具有標準格式。 錯誤可以透過基礎結構通訊協定，例如 WS 尋址，以及較高層級的應用程式通訊協定來使用。

概述

錯誤訊息本文的內容會使用 WS_FAULT 結構在此 API 中表示。 雖然錯誤有一組固定的欄位，可用來提供失敗的相關信息（例如識別錯誤類型的 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 對象的錯誤。

處理用戶端上的錯誤

如果用戶端在使用 Service Proxy 或透過 WsRequestReply 或 WsReceiveMessage時收到錯誤，則會傳回 WS_E_ENDPOINT_FAULT_RECEIVED 錯誤。 （如需詳細資訊，請參閱 Windows Web 服務傳回值。）這些函式也會填入提供給呼叫的 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 函式。

下列列舉是錯誤的一部分：

下列函式是錯誤的一部分：

下列結構是錯誤的一部分：