Задание и обработка сбоев в контрактах и службахSpecifying and Handling Faults in Contracts and Services

Приложения Windows Communication Foundation (WCF) обрабатывают ошибки, выполнив сопоставление объектов управляемого исключения с объектами сбоя SOAP и объектами ошибок SOAP для управляемых объектов исключений.Windows Communication Foundation (WCF) applications handle error situations by mapping managed exception objects to SOAP fault objects and SOAP fault objects to managed exception objects. В подразделах этого раздела описывается, как разрабатывать контракты, чтобы представлять ошибки в виде пользовательских ошибок SOAP, как возвращать эти ошибки в реализации службы, и как клиенты могут перехватывать такие ошибки.The topics in this section discuss how to design contracts to expose error conditions as custom SOAP faults, how to return such faults as part of service implementation, and how clients catch such faults.

Общие сведения об обработке ошибокError Handling Overview

Во всех управляемых приложениях обработка ошибок представлена объектами Exception.In all managed applications, processing errors are represented by Exception objects. В приложениях на основе SOAP, таких как приложения WCF, методы служб обмениваются сведениями об ошибках обработки с помощью сообщений о сбоях SOAP.In SOAP-based applications such as WCF applications, service methods communicate processing error information using SOAP fault messages. Сообщения об ошибках SOAP являются типами сообщения, которые включаются в метаданные, связанные с работой службы, и таким образом создают контракт ошибок, который клиенты могут использовать для повышения надежности и интерактивности своей работы.SOAP faults are message types that are included in the metadata for a service operation and therefore create a fault contract that clients can use to make their operation more robust or interactive. Кроме того, поскольку ошибки SOAP выражаются для клиентов в XML-форме, это система типов с высокой степенью доступности, которую клиенты могут использовать на любой платформе SOAP, увеличивая уровень доступа к приложению WCF.In addition, because SOAP faults are expressed to clients in XML form, it is a highly interoperable type system that clients on any SOAP platform can use, increasing the reach of your WCF application.

Поскольку приложения WCF выполняются в обоих типах систем ошибок, все управляемые сведения об исключениях, отправляемые клиенту, должны быть преобразованы из исключений в ошибки SOAP в службе, отправлены и преобразованы из ошибок SOAP в исключения ошибок в клиентах WCF.Because WCF applications run under both types of error systems, any managed exception information that is sent to the client must be converted from exceptions into SOAP faults on the service, sent, and converted from SOAP faults to fault exceptions in WCF clients. В случае дуплексных клиентов клиентские контракты могут отправлять ошибки SOAP обратно в службу.In the case of duplex clients, client contracts can also send SOAP faults back to a service. В обоих случаях можно использовать поведения исключений для службы по умолчанию или можно явно управлять тем, будут ли исключения сопоставляться с сообщениями об ошибке и как будет выполняться это сопоставление.In either case, you can use the default service exception behaviors, or you can explicitly control whether—and how—exceptions are mapped to fault messages.

Можно отправлять два типа ошибок SOAP: объявленные и необъявленные.Two types of SOAP faults can be sent: declared and undeclared. Объявленные ошибки SOAP представляют ошибки, в которых в операции имеется атрибут System.ServiceModel.FaultContractAttribute, указывающий пользовательский тип ошибки SOAP.Declared SOAP faults are those in which an operation has a System.ServiceModel.FaultContractAttribute attribute that specifies a custom SOAP fault type. Не объявлено Ошибки SOAP не указаны в контракте для операции.Undeclared SOAP faults are not specified in the contract for an operation.

Настоятельно рекомендуется, чтобы операции службы объявляли свои ошибки с помощью атрибута FaultContractAttribute. Это позволит формально указать все ошибки SOAP, которые клиент может получить во время обычной операции.It is strongly recommended that service operations declare their faults by using the FaultContractAttribute attribute to formally specify all SOAP faults that a client can expect to receive in the normal course of an operation. Кроме того, чтобы свести к минимум раскрытие информации, рекомендуется возвращать в ошибке SOAP только те сведения, которые необходимо знать клиенту.It is also recommended that you return in a SOAP fault only the information that a client must know to minimize information disclosure.

Обычно службы (и дуплексные клиенты) выполняют следующие шаги, чтобы интегрировать обработку в свои приложения.Typically, services (and duplex clients) take the following steps to successfully integrate error handling into their applications:

  • Сопоставление исключений и пользовательскими ошибками SOAP.Map exception conditions to custom SOAP faults.

  • Клиенты и службы отправляют и получают ошибки SOAP в виде исключений.Clients and services send and receive SOAP faults as exceptions.

Кроме того, клиенты и службы WCF могут использовать необъявленные ошибки SOAP для отладки и могут расширять поведение при ошибке по умолчанию.In addition, WCF clients and services can use undeclared soap faults for debugging purposes and can extend the default error behavior. В следующих разделах рассматриваются эти задачи и принципы.The following sections discuss these tasks and concepts.

Сопоставление исключений с ошибками SOAPMap Exceptions to SOAP Faults

Первым шагом в создании операции, обрабатывающей ошибки, является определение условий, при которых клиентское приложение должно быть проинформировано об ошибках.The first step in creating an operation that handles error conditions is to decide under what conditions a client application should be informed about errors. Для некоторых операций имеются ошибки, относящиеся к их функциональности.Some operations have error conditions specific to their functionality. Например, операция PurchaseOrder может возвратить конкретную информацию клиенту, которому больше не разрешено размещать заказ на покупку.For example, a PurchaseOrder operation might return specific information to customers who are no longer permitted to initiate a purchase order. В других случаях, например в службе Calculator, более общая ошибка SOAP MathFault может описать все условия ошибки во всей службе.In other cases, such as a Calculator service, a more general MathFault SOAP fault may be able to describe all error conditions across an entire service. После определения ошибок клиентов может быть создана пользовательская ошибка SOAP. Кроме того, можно отметить, что операция возвращает данную эту ошибку при возникновении соответствующей ошибки.Once the error conditions of clients of your service are identified, a custom SOAP fault can be constructed and the operation can be marked as returning that SOAP fault when its corresponding error condition arises.

Дополнительные сведения об этом этапе разработки службы или клиента см. в разделе Определение и указание ошибок.For more information about this step of developing your service or client, see Defining and Specifying Faults.

Клиенты и службы обрабатывают ошибки SOAP в виде исключенийClients and Services Handle SOAP Faults as Exceptions

Определение условий ошибок операций, определение пользовательских ошибок SOAP и пометка этих операций как возвращающие эти ошибки являются первыми этапами успешной обработки ошибок в приложениях WCF.Identifying operation error conditions, defining custom SOAP faults, and marking those operations as returning those faults are the first steps in successful error handling in WCF applications. Следующий шаг заключается в надлежащей реализации отправки и получения этих ошибок.The next step is to properly implement the sending and receiving of these faults. Обычно службы отправляют сообщения об ошибках, чтобы информировать клиентские приложения, но дуплексные клиенты также могут отправлять службам сообщения об ошибках протокола SOAP.Typically services send faults to inform client applications about error conditions, but duplex clients can also send SOAP faults to services.

Дополнительные сведения см. в разделе Отправка и получение ошибок.For more information, see Sending and Receiving Faults.

Необъявленные ошибки протокола SOAP и отладкаUndeclared SOAP Faults and Debugging

Объявленные ошибки протокола SOAP очень полезны для построения надежных распределенных приложений с возможностью взаимодействия.Declared SOAP faults are extremely useful for building robust, interoperable, distributed applications. Однако в некоторых случаях для службы (или дуплексного клиента) полезно отправлять необъявленную ошибку SOAP, которая не упоминается для данной операции в языке WSDL.However, in some cases it is useful for a service (or duplex client) to send an undeclared SOAP fault, one that is not mentioned in the Web Services Description Language (WSDL) for that operation. Например, при разработке службы могут произойти непредвиденные ситуации, в которых для отладки понадобится отправить информацию обратно клиенту.For example, when developing a service, unexpected situations can occur in which it is useful for debugging purposes to send information back to the client. Кроме того, можно задать ServiceBehaviorAttribute.IncludeExceptionDetailInFaults свойство или свойство, чтобы ServiceDebugBehavior.IncludeExceptionDetailInFaults true позволить клиентам WCF получать сведения о внутренних исключениях операций службы.In addition, you can set the ServiceBehaviorAttribute.IncludeExceptionDetailInFaults property or the ServiceDebugBehavior.IncludeExceptionDetailInFaults property to true to permit WCF clients to obtain information about internal service operation exceptions. Как отправка отдельных ошибок, так и Настройка свойств поведения отладки описаны в статье Отправка и получение ошибок.Both sending individual faults and setting the debugging behavior properties are described in Sending and Receiving Faults.

Важно!

Поскольку управляемые исключения могут предоставлять внутренние сведения о приложении, ServiceBehaviorAttribute.IncludeExceptionDetailInFaults устанавливать ServiceDebugBehavior.IncludeExceptionDetailInFaults или true разрешать клиентам WCF получать сведения о внутренних исключениях операций службы, включая персональные и другие конфиденциальные сведения.Because managed exceptions can expose internal application information, setting ServiceBehaviorAttribute.IncludeExceptionDetailInFaults or ServiceDebugBehavior.IncludeExceptionDetailInFaults to true can permit WCF clients to obtain information about internal service operation exceptions, including personally identifiable or other sensitive information.

Присваивать свойству ServiceBehaviorAttribute.IncludeExceptionDetailInFaults или ServiceDebugBehavior.IncludeExceptionDetailInFaults значение true рекомендуется только в качестве временного способа отладки приложения службы.Therefore, setting ServiceBehaviorAttribute.IncludeExceptionDetailInFaults or ServiceDebugBehavior.IncludeExceptionDetailInFaults to true is recommended only as a way to temporarily debug a service application. Кроме того, WSDL для метода, который возвращает такие необработанные управляемые исключения, не содержит контракт для исключения FaultException<TDetail> типа ExceptionDetail.In addition, the WSDL for a method that returns unhandled managed exceptions in this way does not contain the contract for the FaultException<TDetail> of type ExceptionDetail. Клиенты должны рассчитывать на возможность неизвестной ошибки SOAP (возвращается клиентам WCF как System.ServiceModel.FaultException объекты) для правильного получения отладочной информации.Clients must expect the possibility of an unknown SOAP fault (returned to WCF clients as System.ServiceModel.FaultException objects) to obtain the debugging information properly.

Настройка обработки ошибок с помощью интерфейса IErrorHandlerCustomizing Error Handling with IErrorHandler

Если имеются особые требования для настройки ответного сообщения клиента при возникновении исключения на уровне приложения или выполнения специальной обработки после возвращения ответного сообщения, реализуйте интерфейс System.ServiceModel.Dispatcher.IErrorHandler.If you have special requirements to either customize the response message to the client when an application-level exception happens or perform some custom processing after the response message is returned, implement the System.ServiceModel.Dispatcher.IErrorHandler interface.

Проблемы сериализации сбояFault Serialization Issues

При десериализации контракта сбоя службы WCF прежде всего пытаются сопоставить имя контракта сбоя в сообщении протокола SOAP с типом контракта сбоя.When deserializing a fault contract, WCF first attempts to match the fault contract name in the SOAP message with the fault contract type. Если точное соответствие не обнаружено, просматривается список доступных контрактов сбоя в алфавитном порядке для нахождения совместимого типа.If it cannot find an exact match it will then search the list of available fault contracts in alphabetical order for a compatible type. Если совместимые типы имеют два контракта сбоя (например, один является подклассом другого), при десериализации сбоя может быть использован неправильный тип.If two fault contracts are compatible types (one is a subclass of another, for example) the wrong type may be used to de-serialize the fault. Это происходит только в случае, если в контракте сбоя не указано имя, пространство имен и действие.This only occurs if the fault contract does not specify a name, namespace, and action. Во избежание данной проблемы всегда полностью определяйте контракты сбоя, указывая атрибуты имени, пространства имен и действия.To prevent this issue from occurring, always fully qualify fault contracts by specifying the name, namespace, and action attributes. Кроме того, если определено несколько родственных контрактов сбоя, производных от общего базового класса, обязательно помечайте все новые элементы атрибутом [DataMember(IsRequired=true)].Additionally if you have defined a number of related fault contracts derived from a shared base class, make sure to mark any new members with [DataMember(IsRequired=true)]. Дополнительные сведения об использовании атрибута IsRequired см. в разделе DataMemberAttribute.For more information on this IsRequired attribute see, DataMemberAttribute. В этом случае базовый класс не будет считаться совместимым типом, а сбой будет десериализован в правильный производный тип.This will prevent a base class from being a compatible type and force the fault to be deserialized into the correct derived type.

См. такжеSee also