次の方法で共有

障害

  • [アーティクル]

エラー メッセージは、リモート エンドポイントでのエラーに関するエラー情報を伝えるために使用されます。 エラー メッセージは他のメッセージと似ていますが、メッセージ本文の形式には標準の形式があります。 障害は、WS アドレス指定などのインフラストラクチャ プロトコルと、上位レベルのアプリケーション プロトコルの両方で使用できます。

概要

エラー メッセージの本文の内容は、 WS_FAULT 構造体を使用してこの API で表されます。 障害には、障害の種類を識別する WS_FAULT_CODE や、エラーを説明するテキストを含む WS_FAULT_REASON など) に関する情報を提供するために使用される固定のフィールドセットがありますが、エラーに関連する任意の XML コンテンツを指定するために使用できる詳細フィールドも含まれています。

サービスでの障害の生成

通常、サービスは要求の処理中に発生したエラーが原因でエラーを送信します。 この API で使用されるモデルは、処理エラーが発生したサービス内のコードが 、WS_ERROR オブジェクトに必要なエラー情報をキャプチャし、呼び出しチェーンの上位レベルのコードが、下位レイヤーでキャプチャされた情報を使用して実際にエラーを送信するというものです。 このスキームを使用すると、エラーを送信するコードは、エラーの状況をエラーにマップする方法から分離しながら、豊富な障害情報を送信できます。

WsSetFaultErrorProperty では、次のプロパティを使用して、WS_ERROR オブジェクトのエラー情報をキャプチャできます。

  • WS_FAULT_ERROR_PROPERTY_ACTION。 これは、エラー メッセージに使用するアクションを指定します。 これが指定されていない場合は、既定のアクションが指定されます。
  • WS_FAULT_ERROR_PROPERTY_FAULT。 これには、エラー メッセージの本文で送信される WS_FAULT 構造体が含まれます。
  • WS_FAULT_ERROR_PROPERTY_HEADER。 エラーには、要求メッセージのヘッダーに関連する処理エラーを伝えるためにエラー メッセージに追加されるメッセージ ヘッダーが含まれます。 このプロパティを使用して、エラー メッセージに追加するヘッダーを含む WS_XML_BUFFER を指定できます。

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 サービスの戻り値」を参照してください)。これらの関数は、呼び出しに指定された 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 関数を使用します。

次の列挙は、障害の一部です。

次の関数は、障害の一部です。

次の構造体は、障害の一部です。