Поделиться через

Ошибки

  • Статья

Сообщение об ошибке используется для передачи сведений об ошибке в удаленной конечной точке. Сообщение об ошибке аналогично любому другому сообщению, кроме формата текста сообщения имеет стандартный формат. Ошибки могут использоваться как протоколами инфраструктуры, такими как WS-Адресация, так и протоколами приложений более высокого уровня.

Обзор

Содержимое текста сообщения об ошибке представлено в этом API с помощью структуры WS_FAULT. Хотя ошибка имеет фиксированный набор полей, используемых для предоставления сведений о сбое (например, 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 можно использовать для управления подробным описанием ошибки.

При работе с уровнем канала ошибки можно отправлять для объекта WS_ERROR с помощью WsSendFaultMessageForError.

Обработка ошибок на клиенте

Если клиент получает ошибку при использовании прокси-сервера службы или через WsRequestReply или WsReceiveMessage, будет возвращена ошибка WS_E_ENDPOINT_FAULT_RECEIVED. (Дополнительные сведения см. в возвращаемых значений веб-служб Windows.) Эти функции также заполняют объект WS_ERROR, предоставленный вызову с информацией о полученной ошибке.

Следующие свойства объекта WS_ERROR можно запрашивать с помощью WsGetFaultErrorProperty для получения сведений о полученной ошибке:

Ошибка может содержать произвольное дополнительное 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_FAULT с WS_ERROR, используйте функцию WsCreateFaultFromError.

Следующие перечисления являются частью ошибок:

Следующие функции являются частью сбоев:

Следующие структуры являются частью сбоев: