Udostępnij za pośrednictwem

Błędów

  • Artykuł

Komunikat o błędzie służy do przekazywania informacji o błędzie dotyczących błędu w zdalnym punkcie końcowym. Komunikat o błędzie jest podobny do każdego innego komunikatu, z wyjątkiem formatu treści komunikatu ma standardowy format. Błędy mogą być używane zarówno przez protokoły infrastruktury, jak adresowanie WS, jak i protokoły aplikacji wyższego poziomu.

Przegląd

Zawartość treści komunikatu o błędzie jest reprezentowana w tym interfejsie API przy użyciu struktury WS_FAULT. Mimo że błąd ma stały zestaw pól używanych do dostarczania informacji o awarii (takich jak WS_FAULT_CODE, który identyfikuje typ błędu, oraz WS_FAULT_REASON zawierający tekst opisujący błąd), zawiera również pole szczegółów, które można użyć do określenia dowolnej zawartości XML odnoszącej się do błędu.

Generowanie błędów w usłudze

Usługa zazwyczaj wysyła błąd z powodu błędu napotkanego podczas przetwarzania żądania. Model używany przez ten interfejs API polega na tym, że kod w usłudze, który napotka błąd przetwarzania, przechwytuje niezbędne informacje o błędzie w obiekcie WS_ERROR, a następnie kod na wyższym poziomie w łańcuchu wywołań faktycznie wyśle błąd przy użyciu informacji przechwyconych w niższej warstwie. Ten schemat umożliwia kod, który wysyła błąd, aby był odizolowany od tego, w jaki sposób błędy są mapowane na błędy, jednocześnie umożliwiając wysyłanie zaawansowanych informacji o błędach.

Następujące właściwości mogą być używane z WsSetFaultErrorProperty do przechwytywania informacji o błędach dla obiektu WS_ERROR:

  • WS_FAULT_ERROR_PROPERTY_ACTION. Określa akcję do użycia dla komunikatu o błędzie. Jeśli to nie zostanie określone, zostanie podana akcja domyślna.
  • WS_FAULT_ERROR_PROPERTY_FAULT. Zawiera on strukturę WS_FAULT, która jest wysyłana w treści komunikatu o błędzie.
  • WS_FAULT_ERROR_PROPERTY_HEADER. Niektóre błędy obejmują nagłówki komunikatów, które są dodawane do komunikatu o błędzie w celu przekazywania błędów przetwarzania odnoszących się do nagłówków komunikatu żądania. Tej właściwości można użyć do określenia WS_XML_BUFFER zawierającego nagłówek, który ma zostać dodany do komunikatu o błędzie.

Wszystkie ciągi błędów dodawane do obiektu WS_ERROR są używane jako tekst w wysłanym błędzie. Ciągi błędów można dodać do obiektu błędu przy użyciu WsAddErrorString.

Funkcja WsSetFaultErrorProperty może służyć do ustawiania tych właściwości obiektu WS_ERROR.

Aby ustawić szczegóły błędu przechowywanego w obiekcie WS_ERROR, użyj funkcji WsSetFaultErrorDetail. Ta funkcja może służyć do kojarzenia dowolnej zawartości XML z błędem.

hosta usługi automatycznie wysyła błędy przy użyciu powyższych informacji w obiekcie WS_ERROR. Właściwość WS_SERVICE_PROPERTY_FAULT_DISCLOSURE może służyć do kontrolowania sposobu wysyłania szczegółowych informacji o błędzie.

Jeśli pracujesz w warstwie kanału, błędy mogą być wysyłane dla obiektu WS_ERROR przy użyciu WsSendFaultMessageForError.

Obsługa błędów na kliencie

Jeśli klient otrzymuje błąd podczas korzystania z serwera proxy usługi lub za pośrednictwem WsRequestReply lub WsReceiveMessage, zostanie zwrócony błąd WS_E_ENDPOINT_FAULT_RECEIVED. (Aby uzyskać więcej informacji, zobacz wartości zwracane usług sieci Web systemu Windows.) Te funkcje wypełnią również obiekt WS_ERROR dostarczony do wywołania informacjami o odebranych błędach.

Następujące właściwości obiektu WS_ERROR można wykonywać zapytania przy użyciu WsGetFaultErrorProperty w celu uzyskania informacji o odebranym błędzie:

Błąd może zawierać dowolną dodatkową zawartość XML w szczegółach błędu. Dostęp do niego można uzyskać przy użyciu funkcji WsGetFaultErrorDetail.

Używanie błędów z komunikatami

Poniższa sekcja ma zastosowanie w przypadku bezpośredniego radzenia sobie z zawartością treści komunikatu o błędzie.

Zawartość treści komunikatu o błędzie jest reprezentowana przez standardową strukturę WS_FAULT, która ma wbudowaną obsługę serializacji.

Na przykład następujący kod może służyć do zapisania błędu w treści komunikatu:

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

Poniższy kod może służyć do odczytywania błędu z treści komunikatu:

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

Aby dowiedzieć się, czy odebrany komunikat jest błędem, czy nie, można skonsultować się z WS_MESSAGE_PROPERTY_IS_FAULT. Ta właściwość jest ustawiana na podstawie tego, czy pierwszy element w treści jest elementem błędu podczas WsReadMessageStart, czy WsReadEnvelopeStart.

Aby utworzyć WS_FAULT na podstawie WS_ERROR, użyj funkcji WsCreateFaultFromError.

Następujące wyliczenia są częścią błędów:

Następujące funkcje są częścią błędów:

Następujące struktury są częścią błędów: