Spécification et gestion des erreurs dans les contrats et les servicesSpecifying and Handling Faults in Contracts and Services

Les applications Windows Communication Foundation (WCF) gèrent les situations d’erreur en mappant les objets d’exception managée aux objets d’erreur SOAP et aux objets d’erreur SOAP aux objets d’exception managés.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. Les rubriques de cette section expliquent comment concevoir des contrats pour exposer des conditions d'erreur en tant qu'erreurs SOAP personnalisées, comment retourner de telles erreurs dans le cadre de l'implémentation du service et comment les clients interceptent de telles erreurs.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.

Vue d'ensemble de la gestion des erreursError Handling Overview

Dans toutes les applications managées, les erreurs de traitement sont représentées par des objets Exception.In all managed applications, processing errors are represented by Exception objects. Dans les applications basées sur SOAP telles que les applications WCF, les méthodes de service communiquent les informations d’erreur à l’aide de messages d’erreur SOAP.In SOAP-based applications such as WCF applications, service methods communicate processing error information using SOAP fault messages. Les erreurs SOAP sont des types de messages inclus dans les métadonnées d'une opération de service et créent, par conséquent, un contrat d'erreur permettant aux clients d'améliorer la fiabilité ou l'interactivité de leur opération.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. En outre, étant donné que les erreurs SOAP sont exprimées en clients au format XML, il s’agit d’un système de type très interopérable que les clients sur n’importe quelle plateforme SOAP peuvent utiliser, ce qui a pour effet d’améliorer la portée de votre application 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.

Étant donné que les applications WCF s’exécutent sous les deux types de systèmes d’erreur, toutes les informations sur les exceptions managées envoyées au client doivent être converties des exceptions en erreurs SOAP sur le service, envoyées et converties des erreurs SOAP en exceptions d’erreur dans les clients 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. Dans le cas de clients duplex, les contrats clients peuvent aussi renvoyer des erreurs SOAP à un service.In the case of duplex clients, client contracts can also send SOAP faults back to a service. Dans les deux cas, vous pouvez utiliser les comportements d'exception de service par défaut ou vous pouvez contrôler explicitement si (et comment) les exceptions sont mappées aux messages d'erreur.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.

Deux types d’erreurs SOAP peuvent être envoyées : déclarées et non déclarées.Two types of SOAP faults can be sent: declared and undeclared. Les erreurs SOAP déclarées sont celles dans lesquelles une opération contient un attribut System.ServiceModel.FaultContractAttribute qui spécifie un type d'erreur SOAP personnalisé.Declared SOAP faults are those in which an operation has a System.ServiceModel.FaultContractAttribute attribute that specifies a custom SOAP fault type. Non déclaré Les erreurs SOAP ne sont pas spécifiées dans le contrat d’une opération.Undeclared SOAP faults are not specified in the contract for an operation.

Il est vivement recommandé que les opérations de service déclarent leurs erreurs en utilisant l'attribut FaultContractAttribute pour spécifier de manière formelle toutes les erreurs SOAP qu'un client peut s'attendre à recevoir dans le cours normal de l'opération.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. Il est également recommandé de retourner dans une erreur SOAP uniquement les informations qu'un client doit connaître pour réduire la divulgation d'informations.It is also recommended that you return in a SOAP fault only the information that a client must know to minimize information disclosure.

En général, les services (et les clients duplex) exécutent les étapes suivantes pour intégrer la gestion des erreurs dans leurs applications :Typically, services (and duplex clients) take the following steps to successfully integrate error handling into their applications:

  • Mappage des conditions d'exception aux erreurs SOAP personnalisées.Map exception conditions to custom SOAP faults.

  • Les clients et les services envoient et reçoivent des erreurs SOAP comme exceptions.Clients and services send and receive SOAP faults as exceptions.

En outre, les clients et les services WCF peuvent utiliser des erreurs SOAP non déclarées à des fins de débogage et peuvent étendre le comportement d’erreur par défaut.In addition, WCF clients and services can use undeclared soap faults for debugging purposes and can extend the default error behavior. Les sections suivantes traitent de ces tâches et de ces concepts.The following sections discuss these tasks and concepts.

Mappage d'exceptions aux erreurs SOAPMap Exceptions to SOAP Faults

La première étape pour créer une opération qui gère des conditions d'erreur consiste à décider à quelles conditions une application cliente doit être informée des erreurs.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. Certaines opérations ont des conditions d'erreur spécifiques à leurs fonctionnalités.Some operations have error conditions specific to their functionality. Par exemple, une opération PurchaseOrder peut retourner des informations spécifiques aux clients qui ne sont plus autorisés à initialiser une commande fournisseur.For example, a PurchaseOrder operation might return specific information to customers who are no longer permitted to initiate a purchase order. Dans d'autres cas, comme pour un service Calculator, une erreur SOAP MathFault plus générale peut-être en mesure de décrire toutes les conditions d'erreur à travers un service entier.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. Une fois les conditions d'erreur des clients de votre service identifiées, une erreur SOAP personnalisée peut être construite et l'opération peut être marquée comme retournant cette erreur SOAP lorsque la condition d'erreur correspondante se produit.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.

Pour plus d’informations sur cette étape de développement de votre service ou client, consultez définition et spécification des erreurs.For more information about this step of developing your service or client, see Defining and Specifying Faults.

Clients et services gérant les erreurs SOAP en tant qu'exceptionsClients and Services Handle SOAP Faults as Exceptions

L’identification des conditions d’erreur d’opération, la définition des erreurs SOAP personnalisées et le marquage de ces opérations comme retour de ces erreurs sont les premières étapes de la réussite de la gestion des erreurs dans les applications 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. L'étape suivante consiste à implémenter correctement l'émission et la réception de ces erreurs.The next step is to properly implement the sending and receiving of these faults. En général les services envoient des erreurs pour signaler aux applications clientes des conditions d'erreur, mais les clients duplex peuvent également envoyer des erreurs SOAP aux services.Typically services send faults to inform client applications about error conditions, but duplex clients can also send SOAP faults to services.

Pour plus d’informations, consultez envoi et réception d’erreurs.For more information, see Sending and Receiving Faults.

Erreurs SOAP non déclarées et débogageUndeclared SOAP Faults and Debugging

Les erreurs SOAP déclarées sont extrêmement utiles pour construire des applications fiables, interopérables et distribuées.Declared SOAP faults are extremely useful for building robust, interoperable, distributed applications. Toutefois, il est parfois utile pour un service (ou un client duplex) d'envoyer une erreur SOAP non déclarée, c'est-à-dire une erreur qui n'est pas mentionnée dans WSDL (Web Services Description Language) pour une opération.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. Par exemple, lors du développement d'un service, des situations inattendues peuvent se produire et il peut s'avérer utile de renvoyer des informations au client à des fins de débogage.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. En outre, vous pouvez définir la propriété ServiceBehaviorAttribute.IncludeExceptionDetailInFaults ou la propriété ServiceDebugBehavior.IncludeExceptionDetailInFaults sur true pour permettre aux clients WCF d’obtenir des informations sur les exceptions d’opération de service interne.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. L’envoi d’erreurs individuelles et la définition des propriétés de comportement de débogage sont décrits dans envoi et réception d’erreurs.Both sending individual faults and setting the debugging behavior properties are described in Sending and Receiving Faults.

Important

Étant donné que les exceptions managées peuvent exposer des informations d’application internes, la définition de ServiceBehaviorAttribute.IncludeExceptionDetailInFaults ou ServiceDebugBehavior.IncludeExceptionDetailInFaults à true peut permettre aux clients WCF d’obtenir des informations sur les exceptions d’opération de service interne, y compris l’identification personnelle ou d’autres éléments sensibles informations.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.

Par conséquent, affecter à ServiceBehaviorAttribute.IncludeExceptionDetailInFaults ou à ServiceDebugBehavior.IncludeExceptionDetailInFaults la valeur true est recommandé uniquement pour déboguer temporairement une application de service.Therefore, setting ServiceBehaviorAttribute.IncludeExceptionDetailInFaults or ServiceDebugBehavior.IncludeExceptionDetailInFaults to true is recommended only as a way to temporarily debug a service application. De plus, le WSDL pour une méthode qui retourne des exceptions managées non prises en charge de cette façon ne contient pas le contrat pour le FaultException<TDetail> de type 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. Les clients doivent attendre une erreur SOAP inconnue (retournée aux clients WCF en tant qu’objets System.ServiceModel.FaultException) pour obtenir correctement les informations de débogage.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.

Personnalisation de la gestion des erreurs avec IErrorHandlerCustomizing Error Handling with IErrorHandler

Si vous avez des spécifications spéciales pour personnaliser le message de réponse au client lorsqu'une exception au niveau de l'application se produit ou pour effectuer un traitement personnalisé après avoir retourné le message de réponse, implémentez l'interface 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.

Problèmes de sérialisation d'erreurFault Serialization Issues

Lors de la désérialisation d'un contrat d'erreur, WCF essaie d'abord de faire correspondre le nom du contrat d'erreur figurant dans le message SOAP avec le type de contrat d'erreur.When deserializing a fault contract, WCF first attempts to match the fault contract name in the SOAP message with the fault contract type. S'il ne trouve pas de correspondance exacte, il recherche ensuite un type compatible dans la liste des contrats d'erreur disponibles, par ordre alphabétique.If it cannot find an exact match it will then search the list of available fault contracts in alphabetical order for a compatible type. Si deux contrats d'erreur sont des types compatibles (l'un étant une sous-classe de l'autre, par exemple), il est possible que le mauvais soit utilisé pour désérialiser l'erreur.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. Cela ne se produit que lorsque le contrat d'erreur ne spécifie pas de nom, d'espace de noms et d'action.This only occurs if the fault contract does not specify a name, namespace, and action. Pour éviter la survenue de ce problème, qualifiez toujours les contrats d'erreur en spécifiant les attributs de nom, d'espace de noms et d'action.To prevent this issue from occurring, always fully qualify fault contracts by specifying the name, namespace, and action attributes. En outre, si vous avez défini un certain nombre de contrats d'erreur connexes dérivés d'une classe de base partagée, veillez à marquer tout nouveau membre avec [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)]. Pour plus d'informations sur cet attribut IsRequired, consultez DataMemberAttribute.For more information on this IsRequired attribute see, DataMemberAttribute. Cela empêchera une classe de base d'être un type compatible et forcera la désérialisation de l'erreur vers le type dérivé approprié.This will prevent a base class from being a compatible type and force the fault to be deserialized into the correct derived type.

Voir aussiSee also