Definiera och ange fel
SOAP-fel förmedlar information om feltillstånd från en tjänst till en klient och, i duplex-fallet, från en klient till en tjänst på ett driftskompatibelt sätt. I det här avsnittet beskrivs när och hur du definierar anpassat felinnehåll och anger vilka åtgärder som kan returnera dem. Mer information om hur en tjänst eller duplex-klient kan skicka dessa fel och hur ett klient- eller tjänstprogram hanterar dessa fel finns i Skicka och ta emot fel. En översikt över felhantering i WCF-program (Windows Communication Foundation) finns i Ange och hantera fel i kontrakt och tjänster.
Översikt
Deklarerade SOAP-fel är de där en åtgärd har en System.ServiceModel.FaultContractAttribute som anger en anpassad SOAP-feltyp. Odeklarerade SOAP-fel är de som inte anges i kontraktet för en åtgärd. Det här avsnittet hjälper dig att identifiera dessa felvillkor och skapa ett felkontrakt för din tjänst som klienter kan använda för att hantera dessa felvillkor korrekt när de meddelas av anpassade SOAP-fel. De grundläggande uppgifterna är i ordning:
Definiera de felvillkor som en klient för tjänsten ska känna till.
Definiera det anpassade innehållet i SOAP-felen för dessa felvillkor.
Markera dina åtgärder så att de specifika SOAP-fel som de utlöser exponeras för klienter i WSDL.
Definiera felvillkor som klienter bör känna till
SOAP-fel är offentligt beskrivna meddelanden som innehåller felinformation för en viss åtgärd. Eftersom de beskrivs tillsammans med andra åtgärdsmeddelanden i WSDL känner klienterna till och förväntar sig därför att hantera sådana fel när de anropar en åtgärd. Men eftersom WCF-tjänster är skrivna i hanterad kod kan du välja vilka felvillkor i hanterad kod som ska konverteras till fel och returneras till klienten, vilket ger dig möjlighet att separera felvillkor och buggar i tjänsten från den formella felkonversationen som du har med en klient.
I följande kodexempel visas till exempel en åtgärd som tar två heltal och returnerar ett annat heltal. Flera undantag kan genereras här, så när du utformar felkontraktet måste du avgöra vilka felvillkor som är viktiga för klienten. I det här fallet bör tjänsten identifiera undantaget 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
I föregående exempel kan åtgärden antingen returnera ett anpassat SOAP-fel som är specifikt för att dividera med noll, ett anpassat fel som är specifikt för matematiska åtgärder men som innehåller information som är specifik för att dividera med noll, flera fel för flera olika felsituationer eller inget SOAP-fel alls.
Definiera innehållet i felvillkor
När ett feltillstånd har identifierats som ett som kan returnera ett anpassat SOAP-fel är nästa steg att definiera innehållet i felet och se till att innehållsstrukturen kan serialiseras. Kodexemplet i föregående avsnitt visar ett fel som är specifikt för en Divide åtgärd, men om det finns andra åtgärder på Calculator tjänsten kan ett enda anpassat SOAP-fel informera klienten om alla felvillkor för kalkylatorn, Divide inklusive. I följande kodexempel visas skapandet av ett anpassat SOAP-fel, MathFault, som kan rapportera fel som har gjorts med hjälp av alla matematiska åtgärder, inklusive Divide. Klassen kan ange en åtgärd ( Operation egenskapen) och ett värde som beskriver problemet ( ProblemType egenskapen), men klassen och dessa egenskaper måste vara serialiserbara för att kunna överföras till klienten i ett anpassat SOAP-fel. Därför används attributen System.Runtime.Serialization.DataContractAttribute och System.Runtime.Serialization.DataMemberAttribute för att göra typen och dess egenskaper serialiserbara och så driftskompatibla som möjligt.
// 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
Mer information om hur du ser till att dina data är serialiserbara finns i Ange dataöverföring i tjänstkontrakt. En lista över det serialiseringsstöd som tillhandahåller finns i Typer som System.Runtime.Serialization.DataContractSerializer stöds av Data Contract Serializer.
Markera åtgärder för att upprätta felkontraktet
När en serialiserbar datastruktur som returneras som en del av ett anpassat SOAP-fel har definierats är det sista steget att markera åtgärdskontraktet som ett SOAP-fel av den typen. Det gör du genom att System.ServiceModel.FaultContractAttribute använda attributet och skicka den typ av anpassad datatyp som du har skapat. I följande kodexempel visas hur du använder FaultContractAttribute attributet för att ange att Divide åtgärden kan returnera ett SOAP-fel av typen MathFault. Andra matematiska åtgärder kan nu också ange att de kan returnera en 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
En åtgärd kan ange att den returnerar mer än ett anpassat fel genom att markera åtgärden med mer än ett FaultContractAttribute attribut.
Nästa steg för att implementera felkontraktet i åtgärdsimplementeringen beskrivs i avsnittet Skicka och ta emot fel.
Överväganden för SOAP, WSDL och interoperabilitet
I vissa fall, särskilt när du samverkar med andra plattformar, kan det vara viktigt att kontrollera hur ett fel visas i ett SOAP-meddelande eller hur det beskrivs i WSDL-metadata.
Attributet FaultContractAttribute har en Name egenskap som tillåter kontroll över WSDL-felelementets namn som genereras i metadata för det felet.
Enligt SOAP-standarden kan ett fel ha en Action, en Codeoch en Reason. Action Styrs av egenskapenAction. Egenskapen Code och Reason egenskapen är båda egenskaperna för System.ServiceModel.FaultException klassen, som är den överordnade klassen för den generiska System.ServiceModel.FaultException<TDetail>. Egenskapen Code innehåller en SubCode medlem.
När du kommer åt icke-tjänster som genererar fel finns det vissa begränsningar. WCF stöder endast fel med detaljtyper som schemat beskriver och som är kompatibla med datakontrakt. Som nämnts ovan stöder WCF till exempel inte fel som använder XML-attribut i sina detaljtyper eller fel med fler än ett element på den översta nivån i detaljavsnittet.