Especificação e Tratamento de Falhas em Contratos e Serviços
Os aplicativos WCF (Windows Communication Foundation) lidam com situações de erro mapeando objetos de exceção gerenciados para objetos de falha SOAP e objetos de falha SOAP para objetos de exceção gerenciados. Os tópicos desta seção discutem como projetar contratos para expor condições de erro como falhas SOAP personalizadas, como retornar essas falhas como parte da implementação do serviço e como os clientes detetam essas falhas.
Visão geral do tratamento de erros
Em todos os aplicativos gerenciados, os erros de processamento são representados por Exception objetos. Em aplicativos baseados em SOAP, como aplicativos WCF, os métodos de serviço comunicam informações de erro de processamento usando mensagens de falha SOAP. As falhas SOAP são tipos de mensagem incluídos nos metadados de uma operação de serviço e, portanto, criam um contrato de falha que os clientes podem usar para tornar sua operação mais robusta ou interativa. Além disso, como as falhas SOAP são expressas aos clientes no formato XML, é um sistema de tipo altamente interoperável que os clientes em qualquer plataforma SOAP podem usar, aumentando o alcance do seu aplicativo WCF.
Como os aplicativos WCF são executados em ambos os tipos de sistemas de erro, todas as informações de exceção gerenciadas enviadas ao cliente devem ser convertidas de exceções em falhas SOAP no serviço, enviadas e convertidas de falhas SOAP em exceções de falha em clientes WCF. No caso de clientes duplex, os contratos de cliente também podem enviar falhas SOAP de volta para um serviço. Em ambos os casos, você pode usar os comportamentos de exceção de serviço padrão ou pode controlar explicitamente se — e como — as exceções são mapeadas para mensagens de falha.
Dois tipos de falhas SOAP podem ser enviadas: declaradas e não declaradas. Falhas SOAP declaradas são aquelas em que uma operação tem um System.ServiceModel.FaultContractAttribute atributo que especifica um tipo de falha SOAP personalizado. Falhas SOAP não declaradas não são especificadas no contrato para uma operação.
É altamente recomendável que as operações de serviço declarem suas falhas usando o FaultContractAttribute atributo para especificar formalmente todas as falhas SOAP que um cliente pode esperar receber no curso normal de uma operação. Também é recomendável que você retorne em uma falha SOAP apenas as informações que um cliente deve saber para minimizar a divulgação de informações.
Normalmente, os serviços (e clientes duplex) executam as seguintes etapas para integrar com êxito o tratamento de erros em seus aplicativos:
Mapeie condições de exceção para falhas SOAP personalizadas.
Clientes e serviços enviam e recebem falhas SOAP como exceções.
Além disso, os clientes e serviços WCF podem usar falhas soap não declaradas para fins de depuração e podem estender o comportamento de erro padrão. As seções a seguir discutem essas tarefas e conceitos.
Mapear exceções para falhas SOAP
A primeira etapa na criação de uma operação que lida com condições de erro é decidir em que condições um aplicativo cliente deve ser informado sobre erros. Algumas operações têm condições de erro específicas para a sua funcionalidade. Por exemplo, uma PurchaseOrder operação pode retornar informações específicas para clientes que não têm mais permissão para iniciar uma ordem de compra. Em outros casos, como um Calculator serviço, uma falha SOAP mais geral MathFault pode ser capaz de descrever todas as condições de erro em um serviço inteiro. Uma vez que as condições de erro dos clientes do seu serviço são identificadas, uma falha SOAP personalizada pode ser construída e a operação pode ser marcada como retornando essa falha SOAP quando sua condição de erro correspondente surgir.
Para obter mais informações sobre esta etapa de desenvolvimento do serviço ou cliente, consulte Definindo e especificando falhas.
Clientes e serviços lidam com falhas SOAP como exceções
Identificar condições de erro de operação, definir falhas SOAP personalizadas e marcar essas operações como retornando essas falhas são as primeiras etapas para o tratamento bem-sucedido de erros em aplicativos WCF. O próximo passo é implementar corretamente o envio e recebimento dessas falhas. Normalmente, os serviços enviam falhas para informar os aplicativos cliente sobre condições de erro, mas os clientes duplex também podem enviar falhas SOAP para os serviços.
Para obter mais informações, consulte Enviando e recebendo falhas.
Falhas SOAP não declaradas e depuração
As falhas SOAP declaradas são extremamente úteis para a criação de aplicações robustas, interoperáveis e distribuídas. No entanto, em alguns casos, é útil para um serviço (ou cliente duplex) enviar uma falha SOAP não declarada, uma que não é mencionada no Web Services Description Language (WSDL) para essa operação. Por exemplo, ao desenvolver um serviço, podem ocorrer situações inesperadas em que é útil para fins de depuração enviar informações de volta ao cliente. Além disso, você pode definir a ServiceBehaviorAttribute.IncludeExceptionDetailInFaults propriedade ou a ServiceDebugBehavior.IncludeExceptionDetailInFaults propriedade para true permitir que os clientes WCF obtenham informações sobre exceções de operação de serviço interno. O envio de falhas individuais e a definição das propriedades de comportamento de depuração são descritos em Enviando e recebendo falhas.
Importante
Como as exceções gerenciadas podem expor informações internas do aplicativo, definir ServiceBehaviorAttribute.IncludeExceptionDetailInFaults ou ServiceDebugBehavior.IncludeExceptionDetailInFaults permitir true que os clientes WCF obtenham informações sobre exceções de operação de serviço interno, incluindo informações pessoalmente identificáveis ou outras informações confidenciais.
Portanto, a configuração ServiceBehaviorAttribute.IncludeExceptionDetailInFaults ou ServiceDebugBehavior.IncludeExceptionDetailInFaults para true é recomendada apenas como uma maneira de depurar temporariamente um aplicativo de serviço. Além disso, o WSDL para um método que retorna exceções gerenciadas não tratadas dessa maneira não contém o contrato para o FaultException<TDetail> tipo ExceptionDetail. Os clientes devem esperar a possibilidade de uma falha SOAP desconhecida (retornada aos clientes WCF como System.ServiceModel.FaultException objetos) para obter as informações de depuração corretamente.
Personalizando o tratamento de erros com IErrorHandler
Se você tiver requisitos especiais para personalizar a mensagem de resposta para o cliente quando uma exceção no nível do aplicativo acontecer ou executar algum processamento personalizado depois que a mensagem de resposta for retornada, implemente a System.ServiceModel.Dispatcher.IErrorHandler interface.
Problemas de serialização de falhas
Ao desserializar um contrato de falha, o WCF primeiro tenta corresponder o nome do contrato de falha na mensagem SOAP com o tipo de contrato de falha. Se não conseguir encontrar uma correspondência exata, procurará um tipo compatível na lista de contratos de falha disponíveis por ordem alfabética. Se dois contratos de falha são tipos compatíveis (um é uma subclasse de outro, por exemplo), o tipo errado pode ser usado para desserializar a falha. Isso só ocorre se o contrato de falha não especificar um nome, namespace e ação. Para evitar que esse problema ocorra, sempre qualifique totalmente os contratos de falha especificando os atributos name, namespace e action. Além disso, se você tiver definido vários contratos de falha relacionados derivados de uma classe base compartilhada, certifique-se de marcar todos os novos membros com [DataMember(IsRequired=true)]. Para obter mais informações sobre esse IsRequired atributo, DataMemberAttributeconsulte . Isso impedirá que uma classe base seja um tipo compatível e forçará a falha a ser desserializada no tipo derivado correto.