Fouten opgeven en afhandelen in contracten en services
Windows Communication Foundation-toepassingen (WCF) verwerken foutsituaties door beheerde uitzonderingsobjecten toe te passen aan SOAP-foutobjecten en SOAP-foutobjecten aan beheerde uitzonderingsobjecten. In de onderwerpen in deze sectie wordt besproken hoe u contracten ontwerpt om foutvoorwaarden weer te geven als aangepaste SOAP-fouten, hoe u dergelijke fouten kunt retourneren als onderdeel van de service-implementatie en hoe clients dergelijke fouten ondervangen.
Overzicht van foutafhandeling
In alle beheerde toepassingen worden verwerkingsfouten weergegeven door Exception objecten. In SOAP-toepassingen, zoals WCF-toepassingen, communiceren servicemethoden met behulp van SOAP-foutberichten over de verwerking van foutinformatie. SOAP-fouten zijn berichttypen die zijn opgenomen in de metagegevens voor een servicebewerking en daarom een foutcontract maken dat clients kunnen gebruiken om hun bewerking robuuster of interactief te maken. Omdat SOAP-fouten worden uitgedrukt in clients in XML-vorm, is het bovendien een zeer interoperabel typesysteem dat clients op elk SOAP-platform kunnen gebruiken, waardoor het bereik van uw WCF-toepassing wordt vergroot.
Omdat WCF-toepassingen worden uitgevoerd onder beide typen foutsystemen, moeten alle beheerde uitzonderingsgegevens die naar de client worden verzonden, worden geconverteerd van uitzonderingen naar SOAP-fouten in de service, verzonden en geconverteerd van SOAP-fouten naar foutuitzonderingen in WCF-clients. In het geval van duplex-clients kunnen clientcontracten ook SOAP-fouten terugsturen naar een service. In beide gevallen kunt u het standaardgedrag van service-uitzonderingen gebruiken of u kunt expliciet bepalen of en hoe uitzonderingen worden toegewezen aan foutberichten.
Er kunnen twee typen SOAP-fouten worden verzonden: gedeclareerd en gedeclareerd. Gedeclareerde SOAP-fouten zijn fouten waarin een bewerking een System.ServiceModel.FaultContractAttribute kenmerk heeft dat een aangepast SOAP-fouttype aangeeft. Niet-declaratieve SOAP-fouten worden niet opgegeven in het contract voor een bewerking.
Het wordt sterk aanbevolen dat servicebewerkingen hun fouten declareren met behulp van het FaultContractAttribute kenmerk om formeel alle SOAP-fouten op te geven die een client in de normale loop van een bewerking kan verwachten. Het wordt ook aanbevolen dat u in een SOAP-fout alleen de informatie retourneert die een client moet weten om de openbaarmaking van informatie te minimaliseren.
Doorgaans voeren services (en duplex-clients) de volgende stappen uit om foutafhandeling in hun toepassingen te integreren:
Uitzonderingenvoorwaarden toewijzen aan aangepaste SOAP-fouten.
Clients en services verzenden en ontvangen SOAP-fouten als uitzonderingen.
Daarnaast kunnen WCF-clients en -services niet-declaratieve soapfouten gebruiken voor foutopsporing en het standaardfoutgedrag uitbreiden. In de volgende secties worden deze taken en concepten besproken.
Uitzonderingen toewijzen aan SOAP-fouten
De eerste stap bij het maken van een bewerking die foutvoorwaarden afhandelt, is om te bepalen onder welke voorwaarden een clienttoepassing moet worden geïnformeerd over fouten. Sommige bewerkingen hebben foutvoorwaarden die specifiek zijn voor hun functionaliteit. Een bewerking kan bijvoorbeeld PurchaseOrder specifieke informatie retourneren aan klanten die een inkooporder niet meer mogen initiëren. In andere gevallen, zoals een Calculator service, kan een meer algemene MathFault SOAP-fout alle foutvoorwaarden in een hele service beschrijven. Zodra de foutvoorwaarden van clients van uw service zijn geïdentificeerd, kan een aangepaste SOAP-fout worden samengesteld en kan de bewerking worden gemarkeerd als het retourneren van die SOAP-fout wanneer de bijbehorende foutvoorwaarde zich voordoet.
Zie Fouten definiëren en opgeven voor meer informatie over deze stap voor het ontwikkelen van uw service of client.
Clients en services verwerken SOAP-fouten als uitzonderingen
Het identificeren van foutvoorwaarden voor bewerkingen, het definiëren van aangepaste SOAP-fouten en het markeren van deze bewerkingen als het retourneren van deze fouten, zijn de eerste stappen bij het afhandelen van fouten in WCF-toepassingen. De volgende stap is het correct implementeren van het verzenden en ontvangen van deze fouten. Normaal gesproken verzenden services fouten om clienttoepassingen te informeren over foutvoorwaarden, maar duplex-clients kunnen ook SOAP-fouten naar services verzenden.
Zie Verzenden en ontvangen van fouten voor meer informatie.
Niet-declaratie van SOAP-fouten en foutopsporing
Gedeclareerde SOAP-fouten zijn zeer nuttig voor het bouwen van robuuste, interoperabele, gedistribueerde toepassingen. In sommige gevallen is het echter handig voor een service (of duplex-client) om een niet-declaratieve SOAP-fout te verzenden, een die niet wordt vermeld in de WSDL (Web Services Description Language) voor die bewerking. Bij het ontwikkelen van een service kunnen er bijvoorbeeld onverwachte situaties optreden waarin het nuttig is voor foutopsporingsdoeleinden om informatie terug te sturen naar de client. Daarnaast kunt u de ServiceBehaviorAttribute.IncludeExceptionDetailInFaults eigenschap of de ServiceDebugBehavior.IncludeExceptionDetailInFaults eigenschap zo instellen dat true WCF-clients informatie kunnen verkrijgen over uitzonderingen voor interne servicebewerkingen. Zowel het verzenden van afzonderlijke fouten als het instellen van de eigenschappen van foutopsporingsgedrag worden beschreven in Verzenden en Ontvangende fouten.
Belangrijk
Omdat beheerde uitzonderingen interne toepassingsinformatie kunnen blootstellen, kunnen instellingen ServiceBehaviorAttribute.IncludeExceptionDetailInFaults of ServiceDebugBehavior.IncludeExceptionDetailInFaults wcF-clients true toestaan om informatie te verkrijgen over uitzonderingen voor interne servicebewerkingen, waaronder persoonlijk identificeerbare of andere gevoelige informatie.
Daarom wordt het instellen of trueServiceDebugBehavior.IncludeExceptionDetailInFaults instellen ServiceBehaviorAttribute.IncludeExceptionDetailInFaults alleen aanbevolen als een manier om tijdelijk fouten in een servicetoepassing op te sporen. Daarnaast bevat de WSDL voor een methode die op deze manier niet-verwerkte beheerde uitzonderingen retourneert, het contract voor het FaultException<TDetail> type ExceptionDetailniet. Clients moeten de mogelijkheid verwachten van een onbekende SOAP-fout (geretourneerd naar WCF-clients als System.ServiceModel.FaultException objecten) om de foutopsporingsgegevens correct te verkrijgen.
Foutafhandeling aanpassen met IErrorHandler
Als u speciale vereisten hebt om het antwoordbericht aan te passen aan de client wanneer er een uitzondering op toepassingsniveau optreedt of een aangepaste verwerking uitvoert nadat het antwoordbericht is geretourneerd, implementeert u de System.ServiceModel.Dispatcher.IErrorHandler interface.
Problemen met serialisatie van fouten
Bij het deserialiseren van een foutcontract probeert WCF eerst de naam van het foutcontract in het SOAP-bericht te vinden met het type foutcontract. Als er geen exacte overeenkomst kan worden gevonden, wordt in de lijst met beschikbare foutcontracten in alfabetische volgorde gezocht naar een compatibel type. Als twee foutcontracten compatibele typen zijn (een is bijvoorbeeld een subklasse van een andere) kan het verkeerde type worden gebruikt om de fout te de-serialiseren. Dit gebeurt alleen als het foutcontract geen naam, naamruimte en actie opgeeft. Als u wilt voorkomen dat dit probleem optreedt, moet u altijd volledig in aanmerking komen voor foutcontracten door de naam, naamruimte en actiekenmerken op te geven. Als u ook een aantal gerelateerde foutcontracten hebt gedefinieerd die zijn afgeleid van een gedeelde basisklasse, moet u alle nieuwe leden markeren met [DataMember(IsRequired=true)]. Zie voor meer informatie over dit IsRequired kenmerk. DataMemberAttribute Hiermee voorkomt u dat een basisklasse een compatibel type is en dwingt u af dat de fout wordt gedeserialiseerd in het juiste afgeleide type.