Fouten definiëren en opgeven

Artikel
03/02/2024

SOAP-fouten geven informatie over foutconditie over van een service naar een client en, in het dubbelzijdige geval, van een client naar een service op een interoperabele manier. In dit onderwerp wordt besproken wanneer en hoe u aangepaste foutinhoud definieert en opgeeft welke bewerkingen deze kunnen retourneren. Zie Verzenden en ontvangende fouten voor meer informatie over hoe een service of duplex-client deze fouten kan verzenden en hoe een client- of servicetoepassing deze fouten afhandelt. Zie Fouten opgeven en afhandelen in contracten en services voor een overzicht van foutafhandeling in WCF-toepassingen (Windows Communication Foundation).

Overzicht

Gedeclareerde SOAP-fouten zijn fouten waarin een bewerking een System.ServiceModel.FaultContractAttribute aangepast SOAP-fouttype heeft. Niet-declaratieve SOAP-fouten zijn fouten die niet zijn opgegeven in het contract voor een bewerking. Dit onderwerp helpt u bij het identificeren van deze foutvoorwaarden en het maken van een foutcontract voor uw service die clients kunnen gebruiken om deze foutvoorwaarden correct te verwerken wanneer ze worden gewaarschuwd door aangepaste SOAP-fouten. De basistaken zijn, in volgorde:

Definieer de foutvoorwaarden waarover een client van uw service moet weten.
Definieer de aangepaste inhoud van de SOAP-fouten voor deze foutvoorwaarden.
Markeer uw bewerkingen zodat de specifieke SOAP-fouten die ze gooien, worden blootgesteld aan clients in WSDL.

Foutvoorwaarden definiëren die clients moeten kennen

SOAP-fouten worden openbaar beschreven berichten met foutinformatie voor een bepaalde bewerking. Omdat ze samen met andere bewerkingsberichten in WSDL worden beschreven, weten clients dat en daarom verwachten ze dergelijke fouten te verwerken bij het aanroepen van een bewerking. Maar omdat WCF-services zijn geschreven in beheerde code, bepalen welke foutvoorwaarden in beheerde code moeten worden geconverteerd naar fouten en worden geretourneerd naar de client biedt u de mogelijkheid om foutvoorwaarden en fouten in uw service te scheiden van het formele foutgesprek dat u met een client hebt.

In het volgende codevoorbeeld ziet u bijvoorbeeld een bewerking die twee gehele getallen accepteert en een ander geheel getal retourneert. Er kunnen hier verschillende uitzonderingen optreden, dus bij het ontwerpen van het foutcontract moet u bepalen welke foutvoorwaarden belangrijk zijn voor uw klant. In dit geval moet de service de System.DivideByZeroException uitzondering detecteren.

[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

In het voorgaande voorbeeld kan de bewerking ofwel een aangepaste SOAP-fout retourneren die specifiek is voor het delen door nul, een aangepaste fout die specifiek is voor wiskundige bewerkingen, maar die informatie bevat die specifiek is voor het delen door nul, meerdere fouten voor verschillende foutsituaties of helemaal geen SOAP-fout.

De inhoud van foutvoorwaarden definiëren

Zodra een foutvoorwaarde is geïdentificeerd als een fout die nuttig kan zijn om een aangepaste SOAP-fout te retourneren, is de volgende stap het definiëren van de inhoud van die fout en ervoor te zorgen dat de inhoudsstructuur kan worden geserialiseerd. In het codevoorbeeld in de vorige sectie wordt een fout weergegeven die specifiek is voor een Divide bewerking, maar als er andere bewerkingen in de service zijn, kan één aangepaste SOAP-fout de client informeren over alle foutvoorwaarden van de Calculator rekenmachine, Divide opgenomen. In het volgende codevoorbeeld ziet u het maken van een aangepaste SOAP-fout, MathFaultdie fouten kan rapporteren die zijn gemaakt met behulp van alle wiskundige bewerkingen, waaronder Divide. Hoewel de klasse een bewerking (de Operation eigenschap) en een waarde kan opgeven die het probleem (de ProblemType eigenschap) beschrijft, moeten de klasse en deze eigenschappen serialiseerbaar zijn om te worden overgedragen naar de client in een aangepaste SOAP-fout. Daarom worden de System.Runtime.Serialization.DataContractAttribute en System.Runtime.Serialization.DataMemberAttribute kenmerken gebruikt om het type en de eigenschappen serialiseerbaar en zo interoperabel mogelijk te maken.

// 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

Zie Gegevensoverdracht opgeven in servicecontracten voor meer informatie over hoe u ervoor kunt zorgen dat uw gegevens serialiseerbaar zijn. Zie Typen die worden ondersteund door de serialisatiefunctie van het gegevenscontract voor een lijst met serialisatie.System.Runtime.Serialization.DataContractSerializer

Bewerkingen markeren om het foutcontract tot stand te brengen

Zodra een serialiseerbare gegevensstructuur die wordt geretourneerd als onderdeel van een aangepaste SOAP-fout is gedefinieerd, is de laatste stap het markeren van uw bewerkingscontract als het genereren van een SOAP-fout van dat type. Hiervoor gebruikt u het System.ServiceModel.FaultContractAttribute kenmerk en geeft u het type van het aangepaste gegevenstype door dat u hebt samengesteld. In het volgende codevoorbeeld ziet u hoe u het FaultContractAttribute kenmerk gebruikt om op te geven dat de Divide bewerking een SOAP-fout van het type MathFaultkan retourneren. Andere wiskundige bewerkingen kunnen nu ook opgeven dat ze een 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

Een bewerking kan opgeven dat er meer dan één aangepaste fout wordt geretourneerd door die bewerking met meer dan één FaultContractAttribute kenmerk te markeren.

De volgende stap, voor het implementeren van het foutcontract in de implementatie van uw bewerking, wordt beschreven in het onderwerp Fouten verzenden en ontvangen.

Overwegingen voor SOAP, WSDL en interoperabiliteit

In sommige gevallen, met name wanneer u met andere platforms werkt, kan het belangrijk zijn om te bepalen hoe een fout in een SOAP-bericht wordt weergegeven of de manier waarop deze wordt beschreven in de WSDL-metagegevens.

Het FaultContractAttribute kenmerk heeft een Name eigenschap waarmee u de naam van het WSDL-foutelement kunt beheren die wordt gegenereerd in de metagegevens voor die fout.

Volgens de SOAP-standaard kan een fout een Action, a Codeen een Reason. De Action eigenschap wordt beheerd Action . De Code eigenschap en Reason eigenschap zijn beide eigenschappen van de System.ServiceModel.FaultException klasse, de bovenliggende klasse van het algemene System.ServiceModel.FaultException<TDetail>. De Code eigenschap bevat een SubCode lid.

Bij toegang tot niet-services die fouten genereren, bestaan er bepaalde beperkingen. WCF ondersteunt alleen fouten met detailtypen die in het schema worden beschreven en die compatibel zijn met gegevenscontracten. Zoals hierboven vermeld, biedt WCF bijvoorbeeld geen ondersteuning voor fouten die XML-kenmerken gebruiken in hun detailtypen of fouten met meer dan één element op het hoogste niveau in de detailsectie.

Delen via