Web Services Error Handling and Debugging

Agenda Simple SOAP faults Advanced SOAP faults SOAP headers and faults Error handling From a Service Perspective Debugging Web services

Simple SOAP Faults SOAP Error Handling SOAP 1.1 provides standard for error communication SOAP Fault contains error information   Associated with SOAP response   Contained in SOAP Body Only one fault element per message   Specific error information contained in child elements   faultcode, faultstring, faultactor and detail

Simple SOAP Faults Basic SOAP Error Encoding <soap:Envelope xmlns:soap=" soap:Server Server Error

Simple SOAP Faults Fault Element Content Required child elements   faultcode   faultstring Optional child elements   faultactor   detail Represented in.NET managed classes   SoapException   SoapHeaderException

Simple SOAP Faults Exception Serialization ASP.NET serializes errors into a SOAP Fault Web Method SOAP:Fault Serializes ASP.NET Throws IndexOutofBoundsException

Simple SOAP Faults Exception Deserialization In message receivers,.NET deserializes a SOAP Fault into a SoapException Catch SoapException Web Service Client Deserialize SoapException SOAP:Fault

Simple SOAP Faults SOAP Trace Utility Utility for viewing SOAP messages on the wire   Logs incoming and outgoing messages   Use on client or server Proxy-based HTTP only WSE 2.0 Trace Utility:

Simple SOAP Faults Server Configuration Parameters Default error information is not appropriate for a client Control what is revealed in Web.config Set customErrors mode attribute = “On”   No stack information   No function name   No line numbers <customErrors mode=“On”…

Simple SOAP Faults for Web Services and Clients

Advanced SOAP Faults Server Fault Code Signals an error during internal processing   soap:Server The client is not responsible   Error in an affiliated service or sub-system   The same message may succeed later Report detail in   Keep message generic In SOAP 1.2 renamed “Receiver”

Advanced SOAP Faults Client Fault Code Signals a problem with the message   Violates message contract   Bad input data   Failed validation The client is responsible Use to provide additional information   Well-formed XML or text In SOAP 1.2 renamed “Sender”

Advanced SOAP Faults MustUnderstand and VersionMismatch Fault Codes MustUnderstand   Related to SOAP header “mustUnderstand” attribute   Raised if header was mandatory and not understood VersionMismatch   SOAP Envelope is associated with an unsupported namespace  

Advanced SOAP Faults The.NET SoapException Class Models SOAP Fault structure   System.Web.Services.Protocols   Inherits from System.Exception   Thrown by ASMX Web method or CLR Key properties   Message (faultstring)   Code (faultcode)   Actor (faultactor)   Detail (detail)

Advanced SOAP Faults Handling a SoapException Catch SoapException errors   Use structured error handling Synchronous calls   Catch inline Asynchronous calls   Catch in the call-back method Add structured error handling to any method receiving SOAP messages

Advanced SOAP Faults for Web Services and Clients

SOAP Headers and Faults SOAP Header Errors SOAP headers contain operational data   Separate from functional data Processed prior to body MustUnderstand attribute   Defined by SOAP protocol   If “true”, the Web service must process or return MustUnderstand class error.NET SoapHeader class   Models SOAP headers   MustUnderstand and DidUnderstand properties control error state

SOAP Headers and Faults The.NET SoapHeaderException Class Represents SOAP header errors   Can be raised automatically   Or in code Derives from SoapException   Exposes Message, Code, Actor and Detail   Error handling uses same technique as that for SoapException Indicates other types of SOAP errors   Not limited to MustUndersand   SOAP client faults common

SOAP Headers and Faults Processing a SoapHeaderException Body Header Web service Input Soap Message Throw SoapHeaderException Throw SoapHeaderException Body Fault Header Output Soap Message

Error Handling From a Service Perspective Guidance Application errors   Return status information in the message   Do not return a SOAP fault Operational errors   mustUnderstand, for example   Return a SOAP fault

Error Handling From a Service Perspective Useful Error Information Provide meaningful diagnostic information   Exact location of the exception   Associated server call stack   Incident ID Record errors in a durable, accessible data store   Event logs   Trace logs   Databases

Error Handling From a Service Perspective Machine Logs Application event log   Specify source to separate Web service entries   Have appropriate write permissions Custom event log   Organize entries in separate log   Can be created on a local or remote machine   Have appropriate write permissions

Error Handling From a Service Perspective Application Trace Log Always available to Web service   One per Web site   Use trace.axd to view contents   Primarily used in development, not production Configurable through Web.config   Can be enabled or disabled   Number of entries can be limited <trace enabled=“true” requestLimit=“10”…

Error Handling From a Service Perspective Enterprise Instrumentation Framework (EIF) A comprehensive instrumentation framework   Unified API   Configurable through EnterpriseInstrumentation.config May not be available on the customer computer Freely available from Microsoft  

Error Handling From a Service Perspective EIF Event Sinks Govern information destinations   Standard or custom are available   Are configurable EIF Classes ErrorMessageEvent.Raise AuditMessageEvent.Raise Web service Configuration File Event Sinks Event Log Trace service WMI StandardEvent Sinks

Error Handling From a Service Perspective Exception Management Application Block Easy mechanism for logging errors Writes to Event Log by default Fully configurable Custom publishers   SQL Server   WMI  

Error Handling From a Service Perspective

Debugging Web Services Using Visual Studio.NET 2003 Debugging Visual Studio.NET 2003 supports Web services debugging   All Visual Studio debugging features are available   Seamlessly steps between client and Web service code   Can be used with MSSoapT Web service debugging options   Default is to launch Internet Explorer   “Wait for external processes to connect” debugging property

Debugging Web Services Remote Server Debugging Remote Web services can also be debugged using Visual Studio.NET 2003  .NET remote debugging components must be installed on remote server   Remote server must grant user debugger access   Must be part of the Debugger Users group on the remote machine

Debugging Web Services

Summary What you learned  .NET provides programming model for handling SOAP errors   Variety of options available for logging error data   Visual Studio.NET can be used to step through and debug Web services Next steps   Don’t reveal intellectual property   Don’t use SOAP faults for application communication   Proper error analysis critical to success   Choose right logging and instrumentation solution

© 2004 Microsoft Corporation. All rights reserved. This presentation is for informational purposes only. MICROSOFT MAKES NO WARRANTIES, EXPRESS OR IMPLIED, IN THIS SUMMARY. Content created by 3 Leaf Solutions