March 1, 2021
Hot Topics:

Exception Handling in Web Services

  • By Thiru Thangarathinam
  • Send Email »
  • More Articles »

Advantages of Using SoapException

There are a number of advantages to using the SoapException class to convey the exception information back to the consumers of the Web service. They are:

  • Allows us to handle the exceptional conditions in a consistent fashion
  • Based on the SOAP specification
  • By explicitly raising the SoapException, it is possible to communicate more information, such as the reason for the exception, URL of the Web service method, and so on (using properties such as Actor, Code, and Detail)
  • Use of FaultCode to clearly convey the cause for the exception—Due to client or server
  • Use of the Detail property to give a detailed description of the exception information

Handling Exceptions on the Client Side

In this section, we will see how to handle the exceptions raised from the Web service on the client side. To demonstrate this, let us create a new project named CategoriesServiceClient. Once the project is created, add a command button to the default form and name it btnInvoke. Because you need to reference the Web service from the client side, add a Web Reference to the CategoriesService project. You can do this by using the Project->Add Reference menu option. Then, modify the Click event of the command button to look like the following.

private void btnInvoke_Click(object sender, System.EventArgs e)
    Categories cat = new Categories();
MessageBox.Show(cat.AddCategories("<?xml version='1.0'?>
       <Categories xmlns='http://tempuri.org/CategoriesNamespace'>
       <Category><CategoryName>Test Category</CategoryName>
       <CategoryDescription>Test Category Description
  catch(SoapException soapEx)
    //Load the Detail element of the SoaopException object
    XmlDocument doc = new XmlDocument();
    XmlNamespaceManager nsManager = new
    // Add the namespace to the NamespaceManager
    XmlNode categoryNode =
    string errorNumber = 
string errorMessage = 
string errorSource = 
    MessageBox.Show("Error Number is" +  errorNumber);
    MessageBox.Show("Error Message is" + errorMessage);
    MessageBox.Show("Error Source is" + errorSource);
  catch(Exception ex)

The exceptions raised by the Web service need to be handled on the client side. Because the Web service raises all the exceptions in the form of SoapException, the client application code that invokes the Web service should be wrapped in a try...catch block and the first catch block should have the handler for catching the SoapException as shown in the above code. Let us walk through the above lines of code.

We start by creating an instance of the Categories class. After that, we invoke the AddCategories method of the Categories class by passing in the required XML string as an argument. Then, we have a catch block to handle the SoapException raised from the Web service. In this block, we display the source of the exception in a message box. We do this by using the Code property of the SoapException object. The Code property will be set to Client if the exception is caused by an invalid input from the client. If the exception is caused by the Web service code (for example, the database server is down), the Code property will be set to Server.

Then we load the XML data contained in the Detail element of the SoapException object to an XmlDocument object. Similarly to the Web service code, here also we utilize the XmlNamespaceManager object to associate the namespace with the XmlDocument object. Then, we retrieve the values contained in the individual elements and assign them to local variables. Finally, we display the values contained in the local variables using message boxes.

You can download the client code for handling the exceptions along with the support material for this article.

Putting It All Together

Now that we have completed the client application, let us exercise it by running it. If you run the client application, it will display a message box (with the value true), indicating that the categories details have been successfully saved to the database. Now, remove the <CategoryName> element from the input XML data and run the application. You will get a message indicating that the cause of the exception is the Client application and you will also get more information about the exception in the Detail element of the SoapException object.

As mentioned before, if the Web service fails due to some problems on the server side, the Code property of the SoapException object should be set to Server. To test this, modify the connection string in the Web service code to an invalid value. Now, if you run your client application, you will get a message indicating that the cause of the exception is the Server (Web service in this case).


In this article, we have seen how to handle and communicate exceptions back to the consumers of the Web service by using the SoapException object. We have also seen how the SoapException object allows us to communicate the exceptions using the SOAP fault code defined in the SOAP specification. Along the way, we have also discussed the steps involved in handling the raised exception from the client side. Although the application we created was simple in functionality, it should provide a solid foundation for understanding how to raise and handle exceptions from a Web service.

Source Code

The following is the source code for this two part article: ExceptionHandling.zip - 23 kb.

About the Author

Thiru Thangarathinam has many years of experience in architecting, designing, developing and implementing applications using Object Oriented Application development methodologies. He also possesses a thorough understanding of software life cycle (design, development and testing). He is an expert with ASP.NET, .NET Framework, Visual C#.NET, Visual Basic.NET, ADO.NET, XML Web Services and .NET Remoting and holds MCAD for .NET, MCSD and MCP certifications. Thiru has authored numerous books and articles. He can be reached at thiruthangarathinam@yahoo.com.

# # #

Page 2 of 2

This article was originally published on October 7, 2003

Enterprise Development Update

Don't miss an article. Subscribe to our newsletter below.

Thanks for your registration, follow us on our social networks to keep up-to-date