Exception Management

Exception details returned to the consumer should only contain minimal levels of information and not expose any internal implementation details. For example, consider the following system exception that has been allowed to propagate to the consumer.

 System.Exception: User not in managers role    at EmployeeService.employee.GiveBonus(Int32 empID,  Int32 percentage) in c:\inetpub\wwwroot\employeesystem\employee.asmx.cs:line 207 

The exception details shown above reveal directory structure and other details to the service consumer. This information can be used by a malicious user to footprint the virtual directory path and can assist with further attacks.

Web Services can throw three types of exceptions:

• SoapException objects.

  These can be generated by the CLR or by your Web method implementation code.

• SoapHeaderException objects

  These are generated automatically when the consumer sends a SOAP request that the service fails to process correctly.

• Exception objects

  A Web service can throw a custom exception type that derives from System.Exception . The precise exception type is specific to the error condition. For example, it might be one of the standard .NET Framework exception types such as DivideByZeroException , or ArgumentOutOfRangeException and so on.

Regardless of the exception type, the exception details are propagated to the client using the standard SOAP <Fault> element. Clients and Web services built with ASP.NET do not parse the <Fault> element directly but instead deal consistently with SoapException objects. This allows the client to set up try blocks that catch SoapException objects.

Note  

If you throw a SoapException from a custom HTTP module, it is not automatically serialized as a SOAP <Fault> . In this case, you have to create the SOAP <Fault> manually.

Using SoapExceptions

The following code shows a simple WebMethod, where the validation of application logic fails and, as a result, an exception is generated. The error information sent to the client is minimal. In this sample, the client is provided with a help desk reference that can be used to call support. At the Web server, a detailed error description for the help desk reference is logged to aid problem diagnosis.

 using System.Xml; using System.Security.Principal;     [WebMethod] public void GiveBonus(int empID, int percentage) {   // Only managers can give bonuses   // This example uses Windows authentication   WindowsPrincipal wp = (HttpContext.Current.User as WindowsPrincipal);   if( wp.IsInRole(@"Domain\Managers"))   {      // User is authorized to give bonus      . . .   }   else   {     // Log error details on the server. For example:     //    "DOMAIN\Bob tried to give bonus to Employee Id 345667;     //     Access denied because DOMAIN\Bob is not a manager."     // Note: User name is available from wp.Identity.Name         // Return minimal error information to client using a SoapException     XmlDocument doc = new XmlDocument();     XmlNode detail = doc.CreateNode(XmlNodeType.Element,                                     SoapException.DetailElementName.Name,                                     SoapException.DetailElementName.Namespace);     // This is the detail part of the exception     detail.InnerText = "User not authorized to perform requested operation";     throw new SoapException("Message string from your Web service",                             SoapException.ServerFaultCode,                             Context.Request.Url.AbsoluteUri, detail, null );   } } 

The consumer code that handles potential SoapExceptions follows :

 try {   EmployeeService service = new EmployeeService();   Service.GiveBonus(empID,percentage); } catch (System.Web.Services.Protocols.SoapException se) {    // Extract custom message from se.Detail.InnerText    Console.WriteLine("Server threw a soap exception" + se.Detail.InnerText ); } 

Application Level Error Handling in Global.asax

ASP.NET Web applications commonly handle application level exceptions that are allowed to propagate beyond a method boundary in the Application_Error event handler in Global.asax. This feature is not available to Web services, because the Web service's HttpHandler captures the exception before it reaches other handlers.

If you need application level exception handling, create a custom SOAP extension to handle it. For more information, see MSDN article, "Altering the SOAP Message using SOAP Extensions" in the "Building Applications" section of the .NET Framework SDK at http://www.microsoft.com/downloads/details.aspx?FamilyID=9b3a2ca6-3647-4070-9f41-a333c6b9181d&amp;DisplayLang=en .