Envoi et réception des erreurs

Les erreurs SOAP acheminent des informations de condition d'erreur d'un service à un client et, dans le cas duplex, d'un client à un service d'une manière interopérable. En général un service définit le contenu des erreurs personnalisées et spécifie quelles opérations peuvent les retourner. (Pour plus d’informations, consultez Définition et spécification des erreurs.) Cette rubrique explique comment un service ou un client duplex peut envoyer ces erreurs lorsque la condition d’erreur correspondante s’est produite et comment une application cliente ou de service gère ces erreurs. Pour obtenir une vue d’ensemble de la gestion des erreurs dans les applications Windows Communication Foundation (WCF), consultez Spécification et gestion des erreurs dans les contrats et services.

Envoi d'erreurs SOAP

Les erreurs SOAP déclarées sont celles dans lesquelles une opération contient un System.ServiceModel.FaultContractAttribute qui spécifie un type d'erreur SOAP personnalisé. Les erreurs SOAP non déclarées sont celles qui ne sont pas spécifiées dans le contrat d'une opération.

Envoi d'erreurs déclarées

Pour envoyer une erreur SOAP déclarée, détectez la condition d'erreur pour laquelle l'erreur SOAP est appropriée et levez une nouvelle System.ServiceModel.FaultException<TDetail> où le paramètre de type est un nouvel objet du type spécifié dans le FaultContractAttribute pour cette opération. L'exemple de code suivant illustre l'utilisation de FaultContractAttribute pour spécifier que l'opération SampleMethod peut retourner une erreur SOAP avec le type de détail GreetingFault.

[OperationContract]
[FaultContractAttribute(
  typeof(GreetingFault),
  Action="http://www.contoso.com/GreetingFault",
  ProtectionLevel=ProtectionLevel.EncryptAndSign
  )]
string SampleMethod(string msg);

<OperationContract, FaultContractAttribute(GetType(GreetingFault), Action:="http://www.contoso.com/GreetingFault", ProtectionLevel:=ProtectionLevel.EncryptAndSign)> _
Function SampleMethod(ByVal msg As String) As String

Pour acheminer les informations sur l'erreur GreetingFault au client, interceptez la condition d'erreur appropriée et levez une nouvelle System.ServiceModel.FaultException<TDetail> de type GreetingFault avec un nouvel objet GreetingFault comme argument, comme dans l'exemple de code suivant. Si le client est une application cliente WCF, il subit cette erreur en tant qu’exception managée où le type est System.ServiceModel.FaultException<TDetail> de type GreetingFault.

throw new FaultException<GreetingFault>(new GreetingFault("A Greeting error occurred. You said: " + msg));

    Throw New FaultException(Of GreetingFault)(New GreetingFault("A Greeting error occurred. You said: " & msg))
End If

Envoi d'erreurs non déclarées

L’envoi d’erreurs non déclarées peut être très utile pour diagnostiquer et déboguer rapidement des problèmes dans les applications WCF, mais son utilité en tant qu’outil de débogage est limitée. Plus généralement, lors du débogage il est recommandé d'utiliser la propriété ServiceDebugBehavior.IncludeExceptionDetailInFaults. Lorsque vous définissez cette valeur à « true », les clients rencontrent des erreurs telles que des exceptions FaultException<TDetail> de type ExceptionDetail.

Pour envoyer une erreur SOAP non déclarée, levez un objet System.ServiceModel.FaultException (autrement dit, pas le type générique FaultException<TDetail>) et passez la chaîne au constructeur. Cette exception est exposée aux applications clientes WCF en tant qu’exception System.ServiceModel.FaultException levée où la chaîne est disponible en appelant la méthode FaultException<TDetail>.ToString.

Gestion des erreurs

Sur les clients WCF, les erreurs SOAP qui se produisent pendant la communication et qui concernent les applications clientes sont levées en tant qu’exceptions managées. Bien que de nombreuses exceptions puissent se produire durant l’exécution d’un programme, les applications qui utilisent le modèle de programmation WCF peuvent s’attendre à gérer des exceptions des deux types suivants suite à la communication.

• TimeoutException

• CommunicationException

Les objets TimeoutException sont levés lorsqu'une opération dépasse le délai d'attente spécifié.

Les objets CommunicationException sont levés lorsqu'il existe une condition d'erreur de communication récupérable sur le service ou le client.

La classe CommunicationException a deux types dérivés importants, FaultException et le type FaultException<TDetail> générique.

Les exceptions FaultException sont levées lorsqu'un écouteur reçoit une erreur inattendue ou qui n'est spécifiée dans le contrat d'opération ; habituellement, cela se produit lorsque l'application est déboguée et que le service a la propriété ServiceDebugBehavior.IncludeExceptionDetailInFaults définie à true.

Les exceptions FaultException<TDetail> sont levées sur le client lorsqu'une erreur spécifiée dans le contrat d'opération est reçue en réponse à une opération bidirectionnelle (autrement dit, une méthode avec un attribut OperationContractAttribute ayant la valeur IsOneWay affectée à la propriété false).

En général, seules les exceptions FaultException<TDetail>, TimeoutException et CommunicationException sont dignes d'intérêt pour les clients et les services.

Interception des exceptions dans l'ordre correct

Étant donné que FaultException<TDetail> dérive de FaultException et que FaultException dérive de CommunicationException, il est important d'intercepter ces exceptions dans l'ordre approprié. Si, par exemple, vous avez un bloc try/catch dans lequel vous interceptez d'abord CommunicationException, toutes les erreurs SOAP spécifiées et non spécifiées sont gérées à cet emplacement ; les blocs catch suivants destinés à gérer une exception FaultException<TDetail> personnalisée ne sont jamais appelés.

Souvenez-vous qu'une opération peut retourner une quantité d'erreurs spécifiées quelconque. Chaque erreur est un type unique et doit être gérée séparément.

Gestion des exceptions lors de la fermeture du canal

Une grande partie de la discussion précédente traite des erreurs envoyées durant le traitement des messages de l’application, autrement dit des messages envoyés explicitement par le client lorsque l’application cliente appelle des opérations sur l'objet client WCF.

Même avec les objets locaux, l'élimination de l'objet peut déclencher ou masquer des exceptions qui se produisent pendant le processus de recyclage. Quelque chose de semblable peut se produire lorsque vous utilisez des objets clients WCF. Lorsque vous appelez des opérations, vous envoyez des messages sur une connexion établie. La fermeture du canal peut lever des exceptions si la connexion ne peut pas être fermée proprement ou si elle est déjà fermée, même si toutes les opérations ont été retournées correctement.

En général, les canaux d'objets clients sont fermés dans les cas suivants :

• Lorsque l’objet client WCF est recyclé.

• Lorsque l'application cliente appelle ClientBase<TChannel>.Close.

• Lorsque l'application cliente appelle ICommunicationObject.Close.

• Lorsque l'application cliente appelle une opération qui est une opération de fin pour une session.

Dans tous les cas, la fermeture du canal fait en sorte que celui-ci commence à fermer tous les canaux sous-jacents qui peuvent envoyer des messages pour prendre en charge la fonctionnalité complexe au niveau application. Par exemple, lorsqu’un contrat requiert des sessions, une liaison tente d’établir une session en échangeant des messages avec le canal de service jusqu’à ce qu’une session soit établie. Lorsque le canal est fermé, le canal de session sous-jacent signale au service que la session est terminée. Dans ce cas, si le canal a déjà abandonné, est déjà fermé ou est inutilisable (par exemple, lorsqu'un câble réseau est débranché), le canal client ne peut pas signaler au canal de service que la session est terminée et une exception peut être déclenchée.

Abandon du canal si nécessaire

La fermeture du canal pouvant également lever des exceptions, en plus d'intercepter les exceptions dans l'ordre correct il est important d'abandonner le canal utilisé pour effectuer l'appel dans le bloc catch.

Si l'erreur achemine des informations d'erreur spécifiques à une opération et qu'il est encore possible que d'autres puissent l'utiliser, il n'est pas nécessaire d'abandonner le canal (bien que ces cas soient rares). Dans tous les autres cas, il est recommandé d'abandonner le canal. Pour obtenir un exemple illustrant tous ces points, consultez Exceptions attendues.

L'exemple de code suivant indique comment gérer des exceptions SOAP dans une application cliente de base, y compris une erreur déclarée et une erreur non déclarée.

using System;
using System.ServiceModel;
using System.ServiceModel.Channels;
using Microsoft.WCF.Documentation;

public class Client
{
  public static void Main()
  {
    // Picks up configuration from the config file.
    SampleServiceClient wcfClient = new SampleServiceClient();
    try
    {
      // Making calls.
      Console.WriteLine("Enter the greeting to send: ");
      string greeting = Console.ReadLine();
      Console.WriteLine("The service responded: " + wcfClient.SampleMethod(greeting));

      Console.WriteLine("Press ENTER to exit:");
      Console.ReadLine();

      // Done with service.
      wcfClient.Close();
      Console.WriteLine("Done!");
    }
    catch (TimeoutException timeProblem)
    {
      Console.WriteLine("The service operation timed out. " + timeProblem.Message);
      Console.ReadLine();
      wcfClient.Abort();
    }
    catch (FaultException<GreetingFault> greetingFault)
    {
      Console.WriteLine(greetingFault.Detail.Message);
      Console.ReadLine();
      wcfClient.Abort();
    }
    catch (FaultException unknownFault)
    {
      Console.WriteLine("An unknown exception was received. " + unknownFault.Message);
      Console.ReadLine();
      wcfClient.Abort();
    }
    catch (CommunicationException commProblem)
    {
      Console.WriteLine("There was a communication problem. " + commProblem.Message + commProblem.StackTrace);
      Console.ReadLine();
      wcfClient.Abort();
    }
  }
}

Imports System.ServiceModel
Imports System.ServiceModel.Channels
Imports Microsoft.WCF.Documentation

Public Class Client
    Public Shared Sub Main()
        ' Picks up configuration from the config file.
        Dim wcfClient As New SampleServiceClient()
        Try
            ' Making calls.
            Console.WriteLine("Enter the greeting to send: ")
            Dim greeting As String = Console.ReadLine()
            Console.WriteLine("The service responded: " & wcfClient.SampleMethod(greeting))

            Console.WriteLine("Press ENTER to exit:")
            Console.ReadLine()

            ' Done with service. 
            wcfClient.Close()
            Console.WriteLine("Done!")
        Catch timeProblem As TimeoutException
            Console.WriteLine("The service operation timed out. " & timeProblem.Message)
            Console.ReadLine()
            wcfClient.Abort()
        Catch greetingFault As FaultException(Of GreetingFault)
            Console.WriteLine(greetingFault.Detail.Message)
            Console.ReadLine()
            wcfClient.Abort()
        Catch unknownFault As FaultException
            Console.WriteLine("An unknown exception was received. " & unknownFault.Message)
            Console.ReadLine()
            wcfClient.Abort()
        Catch commProblem As CommunicationException
            Console.WriteLine("There was a communication problem. " & commProblem.Message + commProblem.StackTrace)
            Console.ReadLine()
            wcfClient.Abort()
        End Try
    End Sub
End Class

Voir aussi

• FaultException
• FaultException<TDetail>
• System.ServiceModel.CommunicationException
• Expected Exceptions
• Utiliser la fermeture et l’abandon pour libérer des ressources de client WCF