Condividi tramite

Definizione e specificazione dei guasti

Gli errori SOAP trasmettono informazioni sulle condizioni di errore da un servizio a un client e, nel caso duplex, da un client a un servizio in modo interoperabile. Questo argomento illustra quando e come definire il contenuto di errore personalizzato e specificare quali operazioni possono restituirle. Per altre informazioni sul modo in cui 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 Impostazione e gestione degli errori in Contratti e servizi.

Informazioni generali

Gli errori SOAP dichiarati sono quelli in cui un'operazione ha un System.ServiceModel.FaultContractAttribute oggetto che specifica un tipo di errore SOAP personalizzato. Gli errori SOAP non dichiarati sono quelli non specificati nel contratto per un'operazione. In questo argomento vengono identificate le condizioni di errore e viene creato un contratto di errore per il servizio che i client possono usare per gestire correttamente tali condizioni di errore quando vengono notificati da errori SOAP personalizzati. Le attività di base sono, in ordine:

  1. Definire le condizioni di errore che un cliente del tuo servizio dovrebbe conoscere.

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

  3. Contrassegna le operazioni in modo che gli errori SOAP specifici che generano siano esposti ai client nel WSDL.

Definizione delle condizioni di errore che i client devono conoscere

Gli errori SOAP sono messaggi descritti pubblicamente che contengono informazioni sull'errore per una determinata operazione. Poiché vengono descritti insieme ad altri messaggi di operazione in WSDL, i client conoscono e, di conseguenza, prevedono di gestire tali errori quando richiamano un'operazione. Tuttavia, poiché i servizi WCF vengono scritti in codice gestito, decidere quali condizioni di errore nel codice gestito devono essere convertite in errori e restituiti al client offre la possibilità di separare le condizioni di errore e i bug nel servizio dalla conversazione di errore formale con un client.

Nell'esempio di codice seguente, ad esempio, viene illustrata un'operazione che accetta due interi e restituisce un altro numero intero. In questo caso possono essere generate diverse eccezioni, quindi quando si progetta il contratto di errore, è necessario determinare quali condizioni di errore sono importanti per il cliente. 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 specifico per la divisione per zero, un errore personalizzato specifico per le operazioni matematiche, ma che contiene informazioni specifiche per la divisione per zero, più errori per diverse situazioni di errore diverse o nessun errore SOAP.

Definire il contenuto delle condizioni di errore

Dopo che una condizione di errore è stata identificata come una condizione che può restituire un errore SOAP personalizzato, il passaggio successivo consiste nel definire il contenuto dell'errore e assicurarsi che la struttura del contenuto possa essere serializzata. L'esempio di codice nella sezione precedente mostra un errore specifico di un'operazione Divide , ma se sono presenti altre operazioni sul Calculator servizio, un singolo errore SOAP personalizzato può informare il client di tutte le condizioni di errore del calcolatore, Divide incluso. Nell'esempio di codice seguente viene illustrata la creazione di un errore SOAP personalizzato, MathFault, che può segnalare errori eseguiti usando tutte le operazioni matematiche, incluso Divide. Anche se la classe può specificare un'operazione (la Operation proprietà) e un valore che descrive il problema (la ProblemType proprietà), la classe e queste proprietà devono essere serializzabili per essere trasferite al client in un errore SOAP personalizzato. Pertanto, gli System.Runtime.Serialization.DataContractAttribute attributi e System.Runtime.Serialization.DataMemberAttribute vengono usati per rendere serializzabile il tipo e le relative proprietà e il più interoperabile possibile.

// 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 per la serializzazione fornito System.Runtime.Serialization.DataContractSerializer , vedere Tipi supportati dal serializzatore del contratto dati.

Contrassegnare le operazioni per stabilire il contratto di responsabilità

Dopo aver definito una struttura di dati serializzabile restituita come parte di un errore SOAP personalizzato, l'ultimo passaggio consiste nel contrassegnare il contratto dell'operazione come generazione di un errore SOAP di tale tipo. A tale scopo, usare l'attributo System.ServiceModel.FaultContractAttribute e passare il tipo del 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. Altre operazioni basate su matematica possono ora specificare anche che possono restituire un oggetto 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

Un'operazione può specificare che restituisce più errori personalizzati 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 interoperabilità

In alcune circostanze, soprattutto quando si interagisce con altre piattaforme, può essere importante controllare la modalità di visualizzazione di un errore in un messaggio SOAP o il modo in cui viene descritto nei metadati WSDL.

L'attributo FaultContractAttribute ha una Name proprietà che consente il controllo del nome dell'elemento di errore WSDL generato nei metadati per tale errore.

In base allo standard SOAP, un errore può avere un Action, un Code e un Reason. L'oggetto Action è controllato dalla Action proprietà . La proprietà Code e la proprietà Reason sono entrambe proprietà della classe System.ServiceModel.FaultException, che è la classe madre del generico System.ServiceModel.FaultException<TDetail>. La Code proprietà include un SubCode membro.

Quando si accede a servizi non che generano errori, esistono determinate limitazioni. WCF supporta solo errori con tipi di dettaglio descritti dallo schema e compatibili con i contratti dati. Ad esempio, come indicato in precedenza, WCF non supporta errori che usano attributi XML nei relativi tipi di dettaglio o errori con più di un elemento di primo livello nella sezione dei dettagli.

Vedere anche