Ошибки
Сообщение об ошибке используется для передачи сведений об ошибке в удаленной конечной точке. Сообщение об ошибке аналогично любому другому сообщению, за исключением того, что формат текста сообщения имеет стандартный формат. Ошибки могут использоваться как протоколами инфраструктуры, такими как WS-Addressing, так и протоколами приложений более высокого уровня.
Содержимое текста сообщения об ошибке представлено в этом 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 , используются в качестве текста в отправляемой ошибке. Строки ошибок можно добавить в объект error с помощью WsAddErrorString.
Для задания этих свойств объекта WS_ERROR можно использовать функцию WsSetFaultErrorProperty.
Чтобы задать сведения об ошибке, хранящейся в объекте 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 для получения сведений о полученной ошибке:
- WS_FAULT_ERROR_PROPERTY_ACTION. Указывает значение действия сообщения об ошибке.
- WS_FAULT_ERROR_PROPERTY_FAULT. Содержит структуру WS_FAULT , которая была десериализована из текста сообщения об ошибке.
Ошибка может содержать произвольное дополнительное 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_FAULTWS_ERROR, используйте функцию WsCreateFaultFromError .
Следующие перечисления являются частью ошибок:
Следующие функции являются частью ошибок:
- WsCreateFaultFromError
- WsGetFaultErrorDetail
- WsGetFaultErrorProperty
- WsSetFaultErrorDetail
- WsSetFaultErrorProperty
Следующие структуры являются частью ошибок: