Gestion et levée d'exceptions dans les services Web XML

Article
02/27/2011

Cette rubrique est spécifique à une technologie existante. Les services Web XML et les clients du service Web XML doivent à présent être créés à l'aide de Windows Communication Foundation.

Les exceptions levées par une méthode de service Web créée à l'aide d'ASP.NET sont renvoyées au client sous la forme d'une erreur SOAP. Une erreur SOAP est un élément XML Fault dans un message SOAP qui spécifie quand une erreur s'est produite. Elle peut contenir des détails tels que la chaîne d'exception et la source de l'exception. Pour plus d'informations sur les erreurs SOAP, consultez la spécification SOAP sur le site Web W3C (http://www.w3.org/TR/SOAP).

Heureusement, les clients et services Web créés à l'aide d'ASP.NET ne remplissent ni n'analysent directement l'élément XML Fault ; ils utilisent plutôt le modèle de conception commun pour lever et intercepter des exceptions dans le .NET Framework. Un service Web peut lever un SoapException générique ou une exception spécifique au problème, tel qu'un ArgumentOutOfRangeException. Dans les deux cas, ASP.NET sérialise l'exception dans un message SOAP valide en plaçant l'exception dans un élément Fault de SOAP. Lorsque le message SOAP est désérialisé sur un client ASP.NET, l'erreur SOAP est convertie en exception SoapException, avec les détails d'exception placés dans la propriété Message. Un client peut donc installer un bloc try/catch pour intercepter une SoapException. Un exemple de code d'un service Web qui lève une exception est fourni dans Comment : lever des exceptions d'un service Web créé à l'aide d'ASP.NET. Un exemple de code d'un client de service Web qui intercepte une exception est fourni dans Comment : gérer les exceptions levées par une méthode de service Web.

Une application Web peut comprendre plusieurs services Web. Toutefois, l'événement Application_Error dans le fichier de syntaxe Global.asax ne peut pas être utilisé pour la gestion globale des exceptions. Le HttpHandler pour les services Web consomme toute exception qui se produit pendant qu'un service Web s'exécute et la transforme en erreur SOAP avant l'appel de l'événement Application_Error. Générez une extension SOAP pour traiter les exceptions de services Web dans un gestionnaire d'exceptions global. Une extension SOAP peut vérifier l'existence d'une exception dans la méthode ProcessMessage. Dans la méthode ProcessMessage, vérifiez la propriété Exception du SoapMessage passé lorsque la propriété Stage a la valeur AfterSerialize. Pour plus d'informations sur les extensions SOAP, consultez Modification de messages SOAP à l'aide d'extensions SOAP.

Lever des exceptions d'un service Web créé à l'aide d'ASP.NET

Il est possible de renvoyer des erreurs à un client en levant des exceptions. Une méthode de service Web peut le faire des manières suivantes :

Lever une exception SoapException.
Lever une exception SoapHeaderException.
Lever une exception spécifique au problème.
Permettre à ASP.NET de lever l'exception.

Le tableau suivant décrit les exceptions qu'un service Web peut lever explicitement et comment un client ASP.NET reçoit chaque exception :

Type d'exception levé	Que peut faire un service Web, que reçoit un client
Exception autre que SoapException ou SoapHeaderException	Une méthode de service Web détecte un cas d'exception et lève l'exception spécifique, par exemple ArgumentOutOfRangeException. Un client .NET Framework reçoit un SoapException avec les détails sérialisés dans le texte dans la propriété Message.
SoapException	Une méthode de service Web détecte un cas d'exception et lève un SoapException. Elle fournit également des détails supplémentaires concernant le problème. La méthode de service Web remplit la propriété Detail pour fournir ces informations supplémentaires. Un client .NET Framework reçoit la SoapException avec les informations supplémentaires.
SoapHeaderException	Une méthode de service Web détecte un cas d'exception pendant le traitement d'un élément Header SOAP. La méthode de service Web lève un SoapHeaderException, qui se traduit par un élément Fault placé à l'intérieur de l'élément Header de la réponse. D'après la spécification SOAP, l'erreur doit apparaître dans l'en-tête de réponse dans cette situation. Un client .NET Framework reçoit le SoapHeaderException.

Vous devez lever une exception spécifique au problème ou fournir des détails supplémentaires à un SoapException ou SoapHeaderException, comme décrit dans le tableau précédent.

Exceptions non gérées par une méthode de service Web XML

Dans le cas où une méthode de service Web n'intercepte pas une exception qui se produit dans la méthode, le tableau suivant montre comment l'exception est gérée par ASP.NET.

Lorsqu'une exception non gérée se produit	Réaction d'ASP.NET
Pendant l'exécution de la méthode de service Web	L'exception est interceptée par ASP.NET et renvoyée au client. Le client de service Web créé à l'aide du .NET Framework reçoit un SoapException avec les détails d'exception placés dans la propriété Message.
Pendant le traitement des en-têtes SOAP	ASP.NET lève un SoapHeaderException. Un client de service Web créé à l'aide du .NET Framework reçoit le SoapHeaderException.

Voir aussi

Gestion et levée d'exceptions dans les services Web XML

Lever des exceptions d'un service Web créé à l'aide d'ASP.NET

Exceptions non gérées par une méthode de service Web XML

Voir aussi

Tâches

Référence

Concepts

Autres ressources

Ressources supplémentaires