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 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.
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:
Definire le condizioni di errore che un client del servizio deve conoscere.
Definire il contenuto personalizzato degli errori SOAP per tali condizioni di errore.
Contrassegnare le operazioni in modo che gli specifici errori SOAP generati vengano esposti ai client in WSDL.
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.
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.
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.
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.
- FaultContractAttribute
- DataContractAttribute
- DataMemberAttribute
- Specifica e gestione degli errori in contratti e servizi
- Invio e ricezione degli errori
- Procedura: Dichiarare errori nei contratti di servizio
- Informazioni sul livello di protezione
- Procedura: Impostare la proprietà ProtectionLevel
- Definizione del trasferimento dati nei contratti di servizio