Definizione e specifica degli errori

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 un contenuto dell'errore personalizzato e specificare quali operazioni possono restituire tale contenuto. Per ulteriori informazioni su come un servizio, o un client duplex, può inviare questi errori e come vengono gestiti da un client o un'applicazione del servizio, vedere Invio e ricezione degli errori. Per una panoramica sulla gestione degli errori nelle applicazioni Windows Communication Foundation (WCF), vedere Specifica e gestione di errori in contratti e servizi.

Cenni preliminari

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 utilizzare 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 problemi 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(ByVal a As Integer, ByVal b As Integer) _
       As Integer
      If (b==0) Then 
            Throw New Exception("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 utilizzando 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 utilizzati per rendere il tipo e le relative proprietà serializzabili e interoperativi.

Per ulteriori informazioni su come verificare che i dati sono serializzabili, vedere Specifica del trasferimento di dati nei contratti di servizio. Per un elenco del supporto di serializzazione fornito dal serializzatore System.Runtime.Serialization.DataContractSerializer, vedere Tipi supportati dal serializzatore dei contratti 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, utilizzare l'attributo System.ServiceModel.FaultContractAttribute e passare il tipo di dati personalizzato costruito. Nell'esempio di codice seguente viene illustrato come utilizzare 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.

È 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 degli 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. La proprietà Code include un membro SubCode.

Quando si accede a componenti non-service 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 utilizzano attributi XML nei tipi di dettaglio o errori con più di un elemento di primo livello nella sezione dei dettagli.

Vedere anche

Attività

Procedura: dichiarare errori nei contratti di servizio
Procedura: impostare la proprietà ProtectionLevel

Riferimenti

FaultContractAttribute
DataContractAttribute
DataMemberAttribute

Concetti

Specifica e gestione di errori in contratti e servizi
Invio e ricezione degli errori
Informazioni sul livello di protezione
Specifica del trasferimento di dati nei contratti di servizio