Sdílet prostřednictvím

Chyby

  • Článek

Chybová zpráva se používá ke komunikaci informací o chybě o selhání ve vzdáleném koncovém bodu. Chybová zpráva je podobná jakékoli jiné zprávě, s výjimkou formátu textu zprávy má standardní formát. Chyby mohou být používány protokoly infrastruktury, jako je WS-Adresování, a aplikačními protokoly vyšší úrovně.

Přehled

Obsah textu chybové zprávy je v tomto rozhraní API reprezentován pomocí struktury WS_FAULT. I když má chyba pevnou sadu polí, která slouží k poskytování informací o selhání (například WS_FAULT_CODE, která identifikuje typ chyby, a WS_FAULT_REASON obsahující text popisující chybu), obsahuje také podrobné pole, které lze použít k určení libovolného obsahu XML souvisejícího s chybou.

Generování chyb ve službě

Služba obvykle odešle chybu kvůli určité chybě, ke které došlo při zpracování požadavku. Model používaný tímto rozhraním API spočívá v tom, že kód ve službě, která narazí na chybu zpracování, zachytí potřebné informace o chybách v objektu WS_ERROR a kód na vyšší úrovni v řetězci volání skutečně odešle chybu pomocí informací zachycených v nižší vrstvě. Toto schéma umožňuje kód, který odesílá chybu, aby byl izolován od způsobu mapování chyb na chyby a zároveň umožňuje odesílání bohatých informací o chybách.

Následující vlastnosti lze použít s WsSetFaultErrorProperty k zachycení informací o chybách pro objekt WS_ERROR:

Všechny chybové řetězce přidané do objektu WS_ERROR se použijí jako text v odeslané chybě. Do objektu chyby lze přidat řetězce chyb pomocí WsAddErrorString.

Funkci WsSetFaultErrorProperty lze použít k nastavení těchto vlastností objektu WS_ERROR.

Chcete-li nastavit podrobnosti chyby uložené v objektu WS_ERROR, použijte funkci WsSetFaultErrorDetail. Tuto funkci lze použít k přidružení libovolného obsahu XML k chybě.

Hostitel služby automaticky odešle chyby pomocí výše uvedených informací v objektu WS_ERROR. Vlastnost WS_SERVICE_PROPERTY_FAULT_DISCLOSURE lze použít k řízení způsobu odeslání podrobné chyby.

Pokud pracujete na vrstvě kanálu, mohou být chyby odeslány pro objekt WS_ERROR pomocí WsSendFaultMessageForError.

Zpracování chyb v klientovi

Pokud klient obdrží chybu při použití proxy služby nebo prostřednictvím WsRequestReply nebo WsReceiveMessage, vrátí se chyba WS_E_ENDPOINT_FAULT_RECEIVED. (Další informace najdete v tématu návratové hodnoty webových služeb systému Windows.) Tyto funkce také naplní objekt WS_ERROR zadaný do volání informacemi o přijaté chybě.

Následující vlastnosti objektu WS_ERROR lze dotazovat pomocí WsGetFaultErrorProperty získat informace o přijaté chybě:

Chyba může obsahovat libovolný další obsah XML v detailu chyby. K tomu je možné získat přístup pomocí funkce WsGetFaultErrorDetail.

Použití chyb se zprávami

Následující část se týká přímo obsahu textu chybové zprávy.

Obsah těla chybové zprávy je reprezentován standardní WS_FAULT struktury, která má integrovanou podporu serializace.

Například následující kód lze použít k zápisu chyby do textu zprávy:

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

Následující kód lze použít ke čtení chyby z textu zprávy:

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

Pokud chcete zjistit, jestli je přijatá zpráva chybou nebo ne, WS_MESSAGE_PROPERTY_IS_FAULT je možné si prohlédnout. Tato vlastnost je nastavena na základě toho, zda první prvek v těle je prvek chyby během WsReadMessageStart nebo WsReadEnvelopeStart.

K vytvoření WS_FAULTWS_ERRORpoužijte funkci WsCreateFaultFromError.

Následující výčty jsou součástí chyb:

Následující funkce jsou součástí chyb:

Následující struktury jsou součástí chyb: