Ange och hantera fel i kontrakt och tjänster
Windows Communication Foundation-program (WCF) hanterar felsituationer genom att mappa hanterade undantagsobjekt till SOAP-felobjekt och SOAP-felobjekt till hanterade undantagsobjekt. Ämnena i det här avsnittet beskriver hur du utformar kontrakt för att exponera felvillkor som anpassade SOAP-fel, hur du returnerar sådana fel som en del av tjänstimplementeringen och hur klienter fångar sådana fel.
Översikt över felhantering
I alla hanterade program representeras bearbetningsfel av Exception objekt. I SOAP-baserade program, till exempel WCF-program, kommunicerar tjänstmetoder bearbetning av felinformation med hjälp av SOAP-felmeddelanden. SOAP-fel är meddelandetyper som ingår i metadata för en tjänståtgärd och skapar därför ett felkontrakt som klienter kan använda för att göra driften mer robust eller interaktiv. Eftersom SOAP-fel uttrycks för klienter i XML-format är det dessutom ett mycket driftskompatibelt typsystem som klienter på valfri SOAP-plattform kan använda, vilket ökar räckvidden för ditt WCF-program.
Eftersom WCF-program körs under båda typerna av felsystem måste all hanterad undantagsinformation som skickas till klienten konverteras från undantag till SOAP-fel på tjänsten, skickas och konverteras från SOAP-fel till felfel i WCF-klienter. När det gäller duplex-klienter kan klientkontrakt också skicka SOAP-fel tillbaka till en tjänst. I båda fallen kan du använda standardbeteenden för tjänstfel, eller så kan du uttryckligen styra om och hur undantag mappas till felmeddelanden.
Två typer av SOAP-fel kan skickas: deklarerade och odeklarerade. Deklarerade SOAP-fel är de där en åtgärd har ett System.ServiceModel.FaultContractAttribute attribut som anger en anpassad SOAP-feltyp. Odeklarerade SOAP-fel anges inte i kontraktet för en åtgärd.
Vi rekommenderar starkt att tjänståtgärder deklarerar sina fel med hjälp FaultContractAttribute av attributet för att formellt ange alla SOAP-fel som en klient kan förvänta sig att få under en normal åtgärd. Vi rekommenderar också att du returnerar i ett SOAP-fel endast den information som en klient måste känna till för att minimera avslöjandet av information.
Vanligtvis utför tjänster (och duplexklienter) följande steg för att integrera felhantering i sina program:
Mappa undantagsvillkor till anpassade SOAP-fel.
Klienter och tjänster skickar och tar emot SOAP-fel som undantag.
Dessutom kan WCF-klienter och -tjänster använda odeklarerade tvålfel i felsökningssyfte och kan utöka standardfelbeteendet. I följande avsnitt beskrivs dessa uppgifter och begrepp.
Mappa undantag till SOAP-fel
Det första steget i att skapa en åtgärd som hanterar felvillkor är att under vilka förhållanden ett klientprogram ska informeras om fel. Vissa åtgärder har felvillkor som är specifika för deras funktioner. En åtgärd kan till exempel PurchaseOrder returnera specifik information till kunder som inte längre har behörighet att initiera en inköpsorder. I andra fall, till exempel en Calculator tjänst, kan ett mer allmänt MathFault SOAP-fel beskriva alla feltillstånd i en hel tjänst. När felvillkoren för tjänstens klienter har identifierats kan ett anpassat SOAP-fel konstrueras och åtgärden kan markeras som att returnera SOAP-felet när motsvarande feltillstånd uppstår.
Mer information om det här steget för att utveckla tjänsten eller klienten finns i Definiera och ange fel.
Klienter och tjänster hanterar SOAP-fel som undantag
Att identifiera villkor för åtgärdsfel, definiera anpassade SOAP-fel och markera dessa åtgärder som att returnera dessa fel är de första stegen i lyckad felhantering i WCF-program. Nästa steg är att implementera sändning och mottagning av dessa fel korrekt. Vanligtvis skickar tjänster fel för att informera klientprogram om feltillstånd, men duplex-klienter kan också skicka SOAP-fel till tjänster.
Mer information finns i Skicka och ta emot fel.
Odeklarerade SOAP-fel och felsökning
Deklarerade SOAP-fel är mycket användbara för att skapa robusta, driftskompatibla, distribuerade program. I vissa fall är det dock användbart för en tjänst (eller duplexklient) att skicka ett odeklarerat SOAP-fel, ett fel som inte nämns i WSDL (Web Services Description Language) för den åtgärden. När du till exempel utvecklar en tjänst kan oväntade situationer uppstå där det är användbart för felsökningsändamål att skicka tillbaka information till klienten. Dessutom kan du ange ServiceBehaviorAttribute.IncludeExceptionDetailInFaults egenskapen eller ServiceDebugBehavior.IncludeExceptionDetailInFaults egenskapen till så true att WCF-klienter kan hämta information om interna undantag för tjänståtgärder. Både att skicka enskilda fel och ange egenskaperna för felsökningsbeteende beskrivs i Skicka och ta emot fel.
Viktigt!
Eftersom hanterade undantag kan exponera intern programinformation, kan inställning ServiceBehaviorAttribute.IncludeExceptionDetailInFaults eller ServiceDebugBehavior.IncludeExceptionDetailInFaults till true tillåta WCF-klienter att hämta information om interna tjänståtgärdsfel, inklusive personligt identifierbar eller annan känslig information.
Därför rekommenderas inställning ServiceBehaviorAttribute.IncludeExceptionDetailInFaults eller ServiceDebugBehavior.IncludeExceptionDetailInFaults till true endast som ett sätt att tillfälligt felsöka ett tjänstprogram. Dessutom innehåller WSDL för en metod som returnerar ohanterade hanterade undantag på det här sättet inte kontraktet för FaultException<TDetail> typen ExceptionDetail. Klienter måste förvänta sig risken för ett okänt SOAP-fel (returneras till WCF-klienter som System.ServiceModel.FaultException objekt) för att få felsökningsinformationen korrekt.
Anpassa felhantering med IErrorHandler
Om du har särskilda krav på att antingen anpassa svarsmeddelandet till klienten när ett undantag på programnivå inträffar eller utföra viss anpassad bearbetning när svarsmeddelandet returneras implementerar du System.ServiceModel.Dispatcher.IErrorHandler gränssnittet.
Problem med felserierering
När ett felkontrakt deserialiseras försöker WCF först matcha felkontraktets namn i SOAP-meddelandet med felkontraktstypen. Om den inte hittar en exakt matchning söker den i listan över tillgängliga felkontrakt i alfabetisk ordning efter en kompatibel typ. Om två felkontrakt är kompatibla typer (en är en underklass till en annan, till exempel) kan fel typ användas för att av-serialisera felet. Detta inträffar bara om felkontraktet inte anger ett namn, namnområde och en åtgärd. För att förhindra att det här problemet uppstår måste du alltid helt kvalificera felkontrakt genom att ange attributen name, namespace och action. Om du har definierat ett antal relaterade felkontrakt som härletts från en delad basklass bör du också markera alla nya medlemmar med [DataMember(IsRequired=true)]. Mer information om det här IsRequired attributet finns i DataMemberAttribute. Detta förhindrar att en basklass är en kompatibel typ och tvingar felet att deserialiseras till rätt härledd typ.