Cross-Tier Exception Mechanism

This topic covers the mechanism by which exceptions that occur during the processing of Web service methods, are propagated to, and handled by, Commerce Server 2009 R2 client applications.

When a Web service exception is thrown, the type of the exception determines whether it is propagated to the client. Only detail data from exceptions that are part of the predefined exception list within the server assemblies, is propagated to the client. The type of error also determines whether the exception is logged to the event log on the server. Exceptions that are thrown by the server, such as a SqlException, are logged to the event log, but the call stack details are not propagated to the client.

When a Business Management Application receives an exception from the server, the exception type is used to retrieve the correct localized message string that is based on the language setting for the application. The following sections detail the flow of an exception on both the server and client.

Server-Side Exception Flow

The flow of an exception on the server side is as follows:

1. An exception is thrown during processing.

2. The Web service catches the exception and compares it to the exception list that determines whether the exception should be logged, and whether the detail data should be propagated.

   • If the exception is not in the exception list, the exception is logged and the details are stripped. The client will receive a ServerFaultException instead of the original exception information. If customErrors is disabled, this ServerFaultException will contain the message of the original exception. If customErrors is enabled, the ServerFaultException will have no message.

   • If the exception is on the predefined list, the exception type is used to determine whether the exception data should be propagated. The customErrors configuration determines whether the server-side call stack will be included in the SoapException thrown by the server. If customErrors is enabled, the call stack is not included.

3. When the exception detail data is propagated, the <detail> node of the SOAP fault contains the serialized exception information. This data is then returned to the client for deserialization.

Client-Side Exception Flow

The flow of an exception on the client-side is as follows:

1. The client catches the exception in the form of a SOAP exception.

2. It then inspects the detail node to determine whether the exception contains serialized exception information. If it does, the original exception is deserialized and thrown. If the exception details were propagated from the server, the deserialized exception contains an inner exception including the server-side call stack of the exception.

3. Depending on the call site, explicit handling for the exception may be in place. You can do this in the user interface code for the site.

4. If there is no explicit handling for the exception type, an attempt is made to map the exception to a friendly, localized exception message to display to the user. If there is no mapping, the exception is logged to the event log, and re-thrown. If there is no higher-level exception handling scope, the application will close. If Windows Error Reporting is enabled, the error is reported to Microsoft.

See Also

Other Resources

Developing with the Desktop Business Tools Extensibility Kit