Web Services Error Handling and Web Services Error Handling and DebuggingDebugging
Agenda
Simple SOAP faults Advanced SOAP faults SOAP headers and faults Error handling From a Service Perspective Debugging Web services
Simple SOAP FaultsSOAP 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 FaultsBasic SOAP Error Encoding<soap:Envelope
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<soap:Fault>
<faultcode>soap:Server</faultcode>
<faultstring>Server Error</faultstring>
</soap:Fault>
</soap:Body>
</soap:Envelope>
Simple SOAP FaultsFault 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 MethodWeb Method
SOAP:FaultSOAP:Fault
Serializes
ASP.NETASP.NET
ThrowsIndexOutofBoundsExceptionIndexOutofBoundsException
Simple SOAP FaultsException Deserialization In message receivers, .NET deserializes a SOAP
Fault into a SoapException
Catch SoapException Catch SoapException
Web Service Client Web Service Client
DeserializeSoapExceptionSoapException
SOAP:FaultSOAP: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: http://mtaulty.com/blog/archive/2004/05/25/433.aspx
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
<configuration> <system.web> <customErrors mode=“On”…
Simple SOAP Faults Simple SOAP Faults for Web Services and for Web Services and
ClientsClients
Advanced SOAP Faults Server Fault Code Signals an error during internal processing
<faultcode>soap:Server</faultcode> The client is not responsible
Error in an affiliated service or sub-system The same message may succeed later
Report detail in <faultstring> 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 <detail> 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 http://schemas.xmlsoap.org/soap/envelope/
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 Advanced SOAP Faults for Web Faults for Web
Services and ClientsServices 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 FaultsThe .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 serviceWeb 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
<configuration> <system.web> <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
http://www.microsoft.com/downloads
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 SinksEvent 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 E-Mail
Error Handling From a Error Handling From a Service PerspectiveService 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 Debugging Web ServicesServices
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.© 2004 Microsoft Corporation. All rights reserved.This presentation is for informational purposes only. This presentation is for informational purposes only. MICROSOFT MAKES NO WARRANTIES, EXPRESS OR IMPLIED, IN THIS SUMMARY.MICROSOFT MAKES NO WARRANTIES, EXPRESS OR IMPLIED, IN THIS SUMMARY.Content created by 3 Leaf SolutionsContent created by 3 Leaf Solutions