Especificando e lidando com 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 criar contratos para expor condições de erro como falhas SOAP personalizadas, como retornar falhas como parte da implementação do serviço e como os clientes capturam essas falhas.
Visão geral do tratamento de erros
Em todos os aplicativos gerenciados, os erros de processamento são representados por objetos Exception. Em aplicativos WCF (Windows Communication Foundation), 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 mensagens 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 a operação mais robusta ou interativa. Além disso, como as falhas SOAP são expressas aos clientes em formato XML, é um sistema de tipo altamente interoperável que os clientes em qualquer plataforma SOAP podem usar, aumentando o alcance do 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 controlar explicitamente se as exceções são mapeadas para mensagens de falha.
Dois tipos de falhas SOAP podem ser enviados: declaradas e não declaradas. Falhas de SOAP declaradas são aquelas em que uma operação tem um atributo System.ServiceModel.FaultContractAttribute que especifica um tipo de falha de SOAP personalizada. Falhas de 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 atributo FaultContractAttribute 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 se 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) seguem as seguintes etapas para integrar com êxito o tratamento de erros em seus aplicativos:
Mapear 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 do WCF podem usar falhas de 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 quais condições um aplicativo cliente deve ser informado sobre erros. Algumas operações têm condições de erro específicas para sua funcionalidade. Por exemplo, uma operação PurchaseOrder pode retornar informações específicas aos clientes que não têm mais permissão para iniciar uma ordem de compra. Em outros casos, como um serviço Calculator, uma falha SOAP MathFault mais geral pode ser capaz de descrever todas as condições de erro em um serviço inteiro. Depois que as condições de erro dos clientes do serviço forem identificadas, uma falha SOAP personalizada poderá ser construída e a operação poderá 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 de seu 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 da operação, definir falhas SOAP personalizadas e marcar essas operações como retornar essas falhas são as primeiras etapas no tratamento de erros bem-sucedidos em aplicativos WCF. A próxima etapa é implementar corretamente o envio e o recebimento dessas falhas. Normalmente, os serviços enviam falhas para informar os aplicativos cliente sobre condições de erro, mas clientes duplex também podem enviar falhas SOAP aos serviços.
Para obter mais informações, confira Como enviar e receber falhas.
Falhas SOAP não declaradas e depuração
Falhas SOAP declaradas são extremamente úteis para criar aplicativos distribuídos robustos e interoperáveis. No entanto, em alguns casos, é útil que um serviço (ou cliente duplex) envie uma falha SOAP não declarada, que não seja mencionada na WSDL (Linguagem de Descrição dos Serviços Web) para essa operação. Por exemplo, ao desenvolver um serviço, podem ocorrer situações inesperadas nas quais é útil para fins de depuração enviar informações de volta ao cliente. Além disso, você pode definir a propriedade ServiceBehaviorAttribute.IncludeExceptionDetailInFaults ou a propriedade ServiceDebugBehavior.IncludeExceptionDetailInFaults como true para permitir que os clientes do WCF obtenham informações sobre exceções internas de operação de serviço. O envio de falhas individuais e a configuração das propriedades de comportamento de depuração são descritos em Enviando e recebendo falhas.
Importante
Como exceções gerenciadas podem expor informações internas do aplicativo, definir ServiceBehaviorAttribute.IncludeExceptionDetailInFaults ou ServiceDebugBehavior.IncludeExceptionDetailInFaults como true pode permitir que os clientes do WCF obtenham informações sobre exceções de operação de serviço interna, incluindo informações pessoais identificáveis ou outras informações confidenciais.
Portanto, a configurar ServiceBehaviorAttribute.IncludeExceptionDetailInFaults ou ServiceDebugBehavior.IncludeExceptionDetailInFaults como true é recomendado 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 sem tratamento dessa forma não contém o contrato do FaultException<TDetail> do tipo ExceptionDetail. Os clientes devem esperar a possibilidade de uma falha SOAP desconhecida (retornada aos clientes do WCF como objetos System.ServiceModel.FaultException) 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 ocorrer uma exceção no nível do aplicativo ou executar algum processamento personalizado depois que a mensagem de resposta for retornada, implemente a interface System.ServiceModel.Dispatcher.IErrorHandler.
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 encontrar uma correspondência exata, ele pesquisará a lista de contratos de falha disponíveis em ordem alfabética para obter um tipo compatível. Se dois contratos de falha forem tipos compatíveis (um é uma subclasse de outro, por exemplo) o tipo errado poderá ser usado para desserializar a falha. Isso só ocorrerá 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 o nome, o namespace e os atributos de ação. Além disso, se você tiver definido uma série de contratos de falha relacionados derivados de uma classe base compartilhada, marque os novos membros com [DataMember(IsRequired=true)]. Para obter mais informações sobre esse atributo IsRequired, confira DataMemberAttribute. Isso impedirá que uma classe base seja um tipo compatível e forçará a falha a ser desserializada no tipo derivado correto.