Share via

Handling and Throwing Exceptions in XML Web Services

  • Article

This topic is specific to a legacy technology. XML Web services and XML Web service clients should now be created using Windows Communication Foundation.

Exceptions thrown by a Web service method created using ASP.NET are sent back to the client in the form of a SOAP fault. A SOAP fault is a Fault XML element within a SOAP message that specifies when an error occurred. It may contain details such as the exception string and the source of the exception. For details on SOAP faults, see the SOAP specification on the W3C Web site (http://www.w3.org/TR/SOAP).

Fortunately, both clients and Web services created using ASP.NET do not populate or parse the Fault XML element directly, but rather use the common design pattern for throwing and catching exceptions in the .NET Framework. A Web service can throw either a generic SoapException or an exception specific to the problem, such as an ArgumentOutOfRangeException. Either way, ASP.NET serializes the exception into a valid SOAP message by placing the exception into a SOAP Fault element. When the SOAP message is deserialized on an ASP.NET client, the SOAP fault is converted to a SoapException exception, with the exception details placed in the Message property. A client can thus set up a try/catch block to catch a SoapException. A code example of a Web service throwing an exception is provided in How to: Throw Exceptions from a Web Service Created Using ASP.NET. A code example of a Web service client catching an exception is provided in How to: Handle Exceptions Thrown by a Web Service Method.

A Web application can be comprised of multiple Web services. However, the Application_Error event within the Global.asax Syntax file cannot be used for global exception handling. The HttpHandler for Web services consumes any exception that occurs while a Web service is executing and turns it into a SOAP fault before the Application_Error event is called. Build a SOAP extension to process Web service exceptions in a global exception handler. A SOAP extension can check for the existence of an exception in the ProcessMessage method. Within the ProcessMessage method, check the Exception property of the SoapMessage passed when the Stage property is set to AfterSerialize. For details on SOAP extensions, see SOAP Message Modification Using SOAP Extensions.

Throwing Exceptions from a Web Service Created Using ASP.NET

Propagating errors back to a client is done by throwing exceptions. A Web service method can do this in the following ways:

  • Throw a SoapException exception.

  • Throw a SoapHeaderException exception.

  • Throw an exception specific to the problem.

  • Allow ASP.NET to throw the exception.

The following table describes the exceptions a Web service can explicitly throw and how an ASP.NET client receives each exception:

Type of exception thrown What a Web service can do, what a client receives

Exception other than SoapException or SoapHeaderException

A Web service method detects an exception case and throws the specific exception, such as ArgumentOutOfRangeException. A .NET Framework client receives a SoapException with the details serialized into text in the Message property.

SoapException

A Web service method detects an exception case and throws a SoapException. It also provides additional details regarding the problem. The Web service method populates the Detail property to provide this additional information. A .NET Framework client receives the SoapException with the additional information.

SoapHeaderException

A Web service method detects an exception case while processing a SOAP Header element. The Web service method throws a SoapHeaderException, which translates into a Fault element placed inside the response's Header element. The fault must appear in the response header in this situation according to the SOAP specification. A .NET Framework client receives the SoapHeaderException.

You should throw an exception that is specific to the problem or provide extra details to a SoapException or SoapHeaderException, as described in the preceding table.

Exceptions Not Handled by an XML Web Service Method

If a Web service method does not catch an exception that occurs within the method, the following table outlines how the exception is handled by ASP.NET.

When unhandled exception occurs What ASP.NET does

While executing the Web service method

The exception is caught by ASP.NET and thrown back to the client. The Web service client created using the .NET Framework receives a SoapException with the exception details placed in the Message property.

While processing SOAP headers

ASP.NET throws a SoapHeaderException. A Web service client created using the .NET Framework receives the SoapHeaderException.

See Also

Tasks

How to: Throw Exceptions from a Web Service Created Using ASP.NET
How to: Handle Exceptions Thrown by a Web Service Method

Reference

SoapException Class
SoapHeaderException Class

Concepts

Building XML Web Service Clients

Other Resources

Handling and Throwing Exceptions
XML Web Services Using ASP.NET