Partager via

Définition et spécification d’erreurs

Les erreurs SOAP transmettent les informations de condition d’erreur d’un service à un client et, dans le cas duplex, d’un client à un service de manière interopérable. Cette rubrique explique quand et comment définir du contenu d’erreur personnalisé et spécifier les opérations qui peuvent les retourner. Pour plus d’informations sur la façon dont un service ou un client duplex, peuvent envoyer ces erreurs et comment un client ou une application de service gère ces erreurs, consultez Envoi et réception d’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.

Aperçu

Les erreurs SOAP déclarées sont celles dans lesquelles une opération a un System.ServiceModel.FaultContractAttribute type d’erreur SOAP personnalisé. Les erreurs SOAP non déclarées sont celles qui ne sont pas spécifiées dans le contrat pour une opération. Cette rubrique vous aide à identifier ces conditions d’erreur et à créer un contrat d’erreur pour votre service que les clients peuvent utiliser pour gérer correctement ces conditions d’erreur lorsqu’ils sont avertis par des erreurs SOAP personnalisées. Les tâches de base sont, dans l’ordre :

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

  2. Définissez 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 de 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. Étant donné qu’ils sont décrits 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. Toutefois, étant donné que les services WCF sont écrits dans du code managé, le choix des conditions d’erreur dans le code managé à convertir en défauts et à renvoyer au client vous offre la possibilité de séparer les conditions d’erreur et les bogues dans votre service de la conversation formelle que vous avez avec un client.

Par exemple, l’exemple de code suivant montre une opération qui prend deux entiers et retourne un autre entier. Plusieurs exceptions peuvent survenir ici. Par conséquent, lors de la conception du contrat de faute, 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 peut retourner une erreur SOAP personnalisée spécifique à la division par zéro, une erreur personnalisée spécifique aux opérations mathématiques, mais qui contient des informations spécifiques à la division par zéro, plusieurs erreurs pour plusieurs situations d’erreur différentes ou aucune erreur SOAP du tout.

Définir le contenu des conditions d’erreur

Une fois qu’une condition d’erreur a été identifiée comme une condition qui peut renvoyer utilement une erreur SOAP personnalisée, l’étape suivante consiste à définir le contenu de cette erreur et à vérifier que la structure de contenu peut être sérialisée. L’exemple de code de la section précédente montre une erreur spécifique à une Divide opération, mais s’il existe d’autres opérations sur le service, une seule erreur SOAP personnalisée peut informer le client de toutes les conditions d’erreur de la Calculator calculatrice, Divide incluses. L’exemple de code suivant montre la création d’une erreur SOAP personnalisée, MathFaultqui peut signaler des erreurs effectuées à l’aide de toutes les opérations mathématiques, notamment Divide. Bien que la classe puisse spécifier une opération (la Operation propriété) et une valeur qui décrit le problème (la ProblemType propriété), 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 garantir que vos données sont sérialisables, consultez Spécification du transfert de données dans les contrats de service. Pour obtenir la 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 ce faire, utilisez l’attribut System.ServiceModel.FaultContractAttribute et transmettez le 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 mathématiques peuvent désormais spécifier qu’elles peuvent retourner un 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 FaultContractAttribute attributs.

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

Considérations relatives à l’interopérabilité et SOAP, WSDL

Dans certaines circonstances, en particulier lors de l’interopérabilité avec d’autres plateformes, il peut être important de contrôler la façon dont une erreur apparaît dans un message SOAP ou la façon dont elle est décrite dans les métadonnées WSDL.

L’attribut FaultContractAttribute a une Name propriété 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 un Action, un Code, et un Reason. Le Action est contrôlé par la propriété Action. Code propriété et Reason propriété sont toutes deux des propriétés de classe System.ServiceModel.FaultException, qui est la classe parente de la classe générique System.ServiceModel.FaultException<TDetail>. La Code propriété inclut un SubCode membre.

Lorsque vous accédez à des non-services qui génèrent des erreurs, certaines limitations existent. WCF prend uniquement en charge les erreurs avec les types de détails décrits par le schéma et compatibles avec les contrats de données. Par exemple, comme mentionné ci-dessus, WCF ne prend pas en charge les erreurs qui utilisent des attributs XML dans leurs types de détails, ou des erreurs avec plusieurs éléments de niveau supérieur dans la section détail.

Voir aussi

  • Last updated on