Definizione e specifica degli errori

  • Articolo

Gli errori SOAP forniscono informazioni sulla condizione di errore da un servizio a un client e, nel caso duplex, da un client a un servizio in modo interoperativo. In questo argomento viene illustrato quando e come definire il contenuto di un errore personalizzato e specificare quali operazioni possono restituire tale contenuto. Per altre informazioni su come un servizio o un client duplex può inviare tali errori e come un'applicazione client o di servizio gestisce questi errori, vedere invio e ricezione di errori. Per una panoramica della gestione degli errori nelle applicazioni Windows Communication Foundation (WCF), vedere Specifica e gestione di errori in contratti e servizi.

Panoramica

Gli errori SOAP dichiarati sono quelli in cui un'operazione presenta un System.ServiceModel.FaultContractAttribute che specifica un tipo di errore SOAP personalizzato. Gli errori SOAP non dichiarati sono quelli che non vengono specificati nel contratto per un'operazione. In questo argomento viene illustrato come identificare tali condizioni di errore e creare un contratto di errore per il servizio che i client possono usare per gestire correttamente tali condizioni di errore quando vengono segnalate dagli errori SOAP personalizzati. Le attività di base sono descritte di seguito, in ordine progressivo:

  1. Definire le condizioni di errore che un client del servizio deve conoscere.

  2. Definire il contenuto personalizzato degli errori SOAP per tali condizioni di errore.

  3. Contrassegnare le operazioni in modo che gli specifici errori SOAP generati vengano esposti ai client in WSDL.

Definizione delle condizioni di errore che i client devono conoscere

Gli errori SOAP sono messaggi descritti pubblicamente che contengono informazioni sugli errori per una particolare operazione. Poiché vengono descritti insieme ad altri messaggi dell'operazione in WSDL, i client sono al corrente di tali errori e, pertanto, sono pronti a gestirli quando richiamano un'operazione. Tuttavia, poiché i servizi WCF sono scritti in codice gestito, scegliendo quali condizioni di errore nel codice gestito devono essere convertite in errori e restituite al client è possibile separare le condizioni di errore e i bug del servizio dalle comunicazioni formali sugli errori sostenute con un client.

Ad esempio, nell'esempio di codice seguente è mostrata un'operazione che accetta due numeri interi e restituisce un altro numero intero. In questo caso possono essere generate molte eccezioni, pertanto quando si progetta il contratto di errori, è necessario determinare quali condizioni di errore sono importanti per il client. In questo caso, il servizio deve rilevare l'eccezione 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

Nell'esempio precedente l'operazione può restituire un errore SOAP personalizzato che sia specifico della divisione per zero, un errore personalizzato che sia specifico per le operazioni di matematica ma contenga informazioni specifiche per la divisione per zero, più errori per diverse situazioni di errore o nessun errore SOAP.

Definire il contenuto delle condizioni di errore

Dopo aver identificato una condizione di errore adatta per restituire un errore SOAP personalizzato, il passaggio successivo consiste nel definire il contenuto di tale errore e verificare che la struttura del contenuto possa essere serializzata. L'esempio di codice nella sezione precedente mostra un errore specifico per un'operazione Divide. Tuttavia se nel servizio Calculator sono presenti altre operazioni, un solo errore SOAP personalizzato può informare il client di tutte le condizioni di errore della calcolatrice, inclusa l'operazione Divide. Nell'esempio di codice seguente viene illustrata la creazione di un errore SOAP personalizzato, MathFault, che può segnalare gli errori generati usando tutte le operazioni di matematica, inclusa l'operazione Divide. Mentre la classe può specificare un'operazione (la proprietà Operation ) e un valore che descrivono il problema (la proprietà ProblemType ), è necessario che la classe e queste proprietà siano serializzabili per essere trasferite al client in un errore SOAP personalizzato. Pertanto, gli attributi System.Runtime.Serialization.DataContractAttribute e System.Runtime.Serialization.DataMemberAttribute vengono usati per rendere il tipo e le relative proprietà serializzabili e interoperativi.

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

Per altre informazioni su come assicurarsi che i dati siano serializzabili, vedere Specifica del trasferimento dei dati nei contratti di servizio. Per un elenco del supporto della serializzazione fornito da System.Runtime.Serialization.DataContractSerializer, vedere Tipi supportati dal serializzatore di contratti di dati.

Contrassegnare le operazioni per stabilire il contratto di errore

Dopo aver definito una struttura di dati serializzabile che viene restituita come parte di un errore SOAP personalizzato, l'ultimo passaggio consiste nel contrassegnare il contratto dell'operazione per indicare che genera un errore SOAP di quel tipo. Per questo scopo, usare l'attributo System.ServiceModel.FaultContractAttribute e passare il tipo di dati personalizzato costruito. Nell'esempio di codice seguente viene illustrato come usare l'attributo FaultContractAttribute per specificare che l'operazione Divide può restituire un errore SOAP di tipo MathFault. In questo modo anche le altre operazioni matematiche possono specificare che restituiscono 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

È possibile specificare che un'operazione restituisce più di un errore personalizzato contrassegnando tale operazione con più attributi FaultContractAttribute.

Il passaggio successivo, per implementare il contratto di errore nell'implementazione dell'operazione, è descritto nell'argomento invio e ricezione di errori.

Considerazioni su SOAP, WSDL e sull'interoperabilità

In alcune circostanze, specialmente quando si interagisce con altre piattaforme, può essere importante controllare il modo in cui un errore viene visualizzato in un messaggio SOAP o il modo in cui viene descritto nei metadati WSDL.

L'attributo FaultContractAttribute dispone della proprietà Name che consente di controllare il nome dell'elemento di errore WSDL generato nei metadati per tale errore.

In base allo standard SOAP, a un errore può essere associato un elemento Action, un elemento Code e un elemento Reason. L'elemento Action è controllato dalla proprietà Action. Le proprietà Code e Reason fanno entrambe parte della classe System.ServiceModel.FaultException, che costituisce la classe padre dell'eccezione generica System.ServiceModel.FaultException<TDetail>. La proprietà Code include un membro SubCode.

Quando si accede a componenti non del servizio che generano errori, sono presenti alcune limitazioni. WCF supporta solo errori con tipi di dettaglio descritti nello schema e compatibili con i contratti dati. Ad esempio, come accennato in precedenza, WCF non supporta errori che usano attributi XML nei tipi di dettaglio o errori con più di un elemento di primo livello nella sezione dei dettagli.

Vedi anche