Web Services Error Handling and Debugging. Agenda Simple SOAP faults Advanced SOAP faults SOAP headers and faults Error handling From a Service Perspective.

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