共用方式為

錯誤

  • 發行項

錯誤訊息可用來傳達遠端端點失敗的錯誤資訊。 錯誤訊息就像任何其他訊息一樣，但訊息本文的格式具有標準格式。 基礎結構通訊協定可以使用錯誤，例如 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物件傳送錯誤。

處理用戶端上的錯誤

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

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

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

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