Managing Web Service Exceptions

.NET can make it easy to forget that you are calling a web service. When you deal with proxy classes, you often get used to working with a web service as if it were no different than any other method. However, this can be dangerous. Web methods are different. One big difference is the way in which you throw exceptions from a web service. The following sections explore how to throw exceptions.

Creating a Web Service Exception

Fortunately, the SOAP specification describes how an exception is thrown over the Web through this protocol. These exceptions can be business logic exceptions or those generated by .NET when processing a call. The important point is that if you wrap these exceptions appropriately, the client should be able to understand how to manage them.

.NET provides the SoapException object for wrapping an exception for SOAP transmission. This class has a number of parameters that you may not be used to working with when throwing exceptions. The parameters and properties include the following:

• MessageUsed to define a descriptive message of the exception. If you are passing a standard .NET exception through SOAP, you can set the Message property to the Message property of the standard exception.

• CodeUsed to indicate whether the error was server or client related. You set the property to ServerFaultCode if the client passed the message correctly but the server failed to process the request (was down or broken). You set this value to ClientFaultCode is the client passed a bad message or bad parameter values.

• ActorUsed to set the value to the URI of the web service. The actor is the code that caused the exception.

• Detail (Optional)Used to pass more information about a given error. The Detail property can include nothing or as much detail as you want to include about the exception.

Listing 16.6 shows a new version of the GetCustomerProfile web method. This version checks to see whether the customer exists. If not, it throws a SoapException with the Code property set to ClientFaultCode.

Listing 16.6. Creating a SOAP Exception

[WebMethod(Description = "Used to return a customer's profile.")] public BusinessEntities.Customer GetCustomerProfile(int customerId) {   EntityServices.CustomerProfile custProfile = new EntityServices.CustomerProfile();   BusinessEntities.Customer customer = custProfile.GetCustomer(customerId);   if (customer == null) {     SoapException soapEx = new SoapException("Could not find Customer",       SoapException.ClientFaultCode, Context.Request.Url.AbsoluteUri.ToString());       throw soapEx;    }    return customer; }

Handling a Web Service Exception

You handle the SOAP exception by catching it the same way you might catch any other .NET exception. You can use the .NET SoapException class for this purpose. .NET will automatically translate the SOAP exception into this object for your use. The following simple example shows how to catch the exception and display it in a message box. We added this code to our Windows form example.

} catch (System.Web.Services.Protocols.SoapException ex) {   string msg = "Message: " + ex.Message + ", Actor: " + ex.Actor     + ", Fault Code: " + ex.Code.ToString();   MessageBox.Show(msg); }