Définition et spécification des erreurs

  • Article

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. Cette rubrique explique quand et comment définir le contenu d'erreur personnalisé et spécifier quelles opérations peuvent les retourner. Pour plus d’informations sur la manière dont un service ou un client duplex peut envoyer ces erreurs et comment une application de service ou cliente gère ces erreurs, consultez Envoi et réception des 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.

Vue d’ensemble

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. Cette rubrique vous permet d'identifier ces conditions d'erreur et crée un contrat d'erreur pour votre service que les clients peuvent utiliser pour traiter correctement ces conditions d'erreur lorsqu'elles sont notifiées par des erreurs SOAP personnalisées. Les tâches de base sont, dans l’ordre :

  1. Définir les conditions d'erreur qu'un client de votre service doit connaître.

  2. Définir le contenu personnalisé des erreurs SOAP pour ces conditions d'erreur.

  3. Marquer vos opérations afin que les erreurs SOAP spécifiques qu'elles génèrent soient exposées aux clients dans WSDL.

Définition des conditions d'erreur que les clients doivent connaître

Les erreurs SOAP sont des messages décrits publiquement qui contiennent des informations d'erreur pour une opération particulière. Comme elles sont décrites avec d'autres messages d'opération dans WSDL, les clients savent et, par conséquent, s'attendent à gérer ces erreurs lors de l'appel d'une opération. Mais comme les services WCF sont écrits en code managé, décider quelles conditions d’erreur en code managé seront converties en erreurs et retournées au client vous permet de séparer des conditions d’erreur et des bogues dans votre service de la conversation d’erreur formelle que vous avez avec un client.

Par exemple, l'exemple de code suivant affiche une opération qui accepte deux entiers et retourne un autre entier. Plusieurs exceptions peuvent être levées dans ce contexte, donc lorsque vous concevez le contrat d'erreur, vous devez déterminer quelles conditions d'erreur sont importantes pour votre client. Dans ce cas, le service doit détecter l'exception System.DivideByZeroException.

[ServiceContract]  
public class CalculatorService  
{  
    [OperationContract]
    int Divide(int a, int b)  
    {  
      if (b==0) throw new Exception("Division by zero!");  
      return a/b;  
    }  
}  

<ServiceContract> _
Public Class CalculatorService
    <OperationContract> _
    Public Function Divide(a As Integer, b As Integer) As Integer
        If b = 0 Then Throw New DivideByZeroException("Division by zero!")
        Return a / b
    End Function
End Class

Dans l'exemple précédent, l'opération retourne une erreur SOAP personnalisée qui est spécifique à une division par zéro, une erreur personnalisée qui est spécifique aux opérations de mathématique mais qui contient des informations spécifiques à une division par zéro, des erreurs multiples pour plusieurs situations d'erreur différentes ou aucune erreur SOAP.

Définir le contenu des conditions d'erreur

Une fois qu'une condition d'erreur a été identifiée comme une condition qui peut retourner de façon utile une erreur SOAP personnalisée, l'étape suivante consiste à définir le contenu de cette erreur et garantir que la structure de contenu peut être sérialisée. L'exemple de code dans la section précédente affiche une erreur spécifique à une opération Divide, mais s'il y a d'autres opérations sur le service Calculator, une erreur SOAP personnalisée unique peut informer le client de toutes les conditions d'erreur de calculatrice, y compris Divide. L'exemple de code suivant affiche la création d'une erreur SOAP personnalisée, MathFault, qui peut signaler des erreurs faites à l'aide de toutes les opérations mathématique, y compris Divide. Si la classe peut spécifier une opération (la propriété Operation) et une valeur qui décrit le problème (la propriété ProblemType), la classe et ces propriétés doivent être sérialisables pour être transférées au client dans une erreur SOAP personnalisée. Par conséquent, les attributs System.Runtime.Serialization.DataContractAttribute et System.Runtime.Serialization.DataMemberAttribute sont utilisés pour rendre le type et ses propriétés sérialisables et aussi interopérables que possible.

// Define a math fault data contract
[DataContract(Namespace="http://Microsoft.ServiceModel.Samples")]
public class MathFault
{
    private string operation;
    private string problemType;

    [DataMember]
    public string Operation
    {
        get { return operation; }
        set { operation = value; }
    }

    [DataMember]
    public string ProblemType
    {
        get { return problemType; }
        set { problemType = value; }
    }
}

' Define a math fault data contract
<DataContract([Namespace]:="http://Microsoft.ServiceModel.Samples")> _
Public Class MathFault

    Private m_operation As String
    Private m_problemType As String

    <DataMember()> _
    Public Property Operation() As String

        Get

            Return m_operation

        End Get

        Set(ByVal value As String)

            m_operation = value

        End Set

    End Property

    <DataMember()> _
    Public Property ProblemType() As String

        Get

            Return m_problemType

        End Get

        Set(ByVal value As String)

            m_problemType = value

        End Set

    End Property

End Class

Pour plus d’informations sur la façon de vous assurer que vos données sont sérialisables, consultez Spécification du transfert de données dans des contrats de service. Pour obtenir une liste de la prise en charge de la sérialisation offerte par System.Runtime.Serialization.DataContractSerializer, consultez Types pris en charge par le sérialiseur de contrat de données.

Marquer des opérations pour établir le contrat d'erreur

Une fois qu'une structure de données sérialisable retournée dans le cadre d'une erreur SOAP personnalisée est définie, la dernière étape consiste à marquer votre contrat d'opération comme ayant retourné une erreur SOAP de ce type. Pour cela, utilisez l'attribut System.ServiceModel.FaultContractAttribute et passez le type du type de données personnalisé que vous avez construit. L'exemple de code suivant montre comment utiliser l'attribut FaultContractAttribute pour spécifier que l'opération Divide peut retourner une erreur SOAP de type MathFault. D'autres opérations de mathématique peuvent désormais aussi spécifier qu'elles peuvent retourner une MathFault.

[OperationContract]
[FaultContract(typeof(MathFault))]
int Divide(int n1, int n2);

<OperationContract()> _
<FaultContract(GetType(MathFault))> _
Function Divide(ByVal n1 As Integer, ByVal n2 As Integer) As Integer

Une opération peut spécifier qu'elle retourne plusieurs erreurs personnalisées en marquant cette opération avec plusieurs attributs FaultContractAttribute.

L’étape suivante, pour implémenter le contrat d’erreur dans votre implémentation d’opération, est décrite dans la rubrique Envoi et réception des erreurs.

Considérations sur SOAP, WSDL et l'interopérabilité

Dans certaines circonstances, en particulier lors de l'interaction avec d'autres plateformes, il peut être important de contrôler la manière dont se manifeste une erreur dans un message SOAP ou sa description dans les métadonnées WSDL.

L'attribut FaultContractAttribute a une propriété Name qui autorise le contrôle du nom d'élément d'erreur WSDL généré dans les métadonnées pour cette erreur.

Selon la norme SOAP, une erreur peut avoir une Action, un Code et une Reason. Action est contrôlé par la propriété Action. La propriété Code et la propriété Reason sont deux propriétés de la classe System.ServiceModel.FaultException qui est la classe parente du System.ServiceModel.FaultException<TDetail> générique. La propriété Code comprend un membre SubCode.

Lors de l'accès à des non-services sources d'erreurs, certaines limitations existent. WCF prend en charge uniquement des erreurs avec des types de détail que le schéma décrit et qui sont compatibles avec les contrats de données. Par exemple, comme indiqué ci-dessus, WCF ne prend pas en charge les erreurs qui utilisent des attributs XML dans leur type de détail ou des erreurs contenant plusieurs éléments de niveau supérieur dans la section de détail.

Voir aussi