Callback Exception Handling

Jun 21, 2024
6 minutes to read

Typically, when a web component sends a callback that is processed on the server side and an unhandled server error occurs, the web application becomes unresponsive to the end-user (i.e., it crashes or hangs in the client’s browser). DevExpress ASP.NET components (Web Forms controls and MVC extensions) implement a built-in callback error-handling mechanism so that the application remains responsive.

ASPxHttpHandlerModule includes an error-handling mechanism to catch unhandled server exceptions while callbacks are processed. The module generates and sends a response that contains exception-related information - so that the application stays responsive.

By default, error messages are displayed in a browser based on the web component that initiated the callback as follows.

For an AJAX-enabled DevExpress web component - error information is shown within the component’s UI element;
For an external components - error details are displayed within a popup message box.

The error message sent to a remote client depends on the mode attribute setting defined in Web.config‘s <customErrors> section.

Displaying Message Text for Callback Errors

If an unhandled exception occurs while a DevExpress web component’s callback is processed on the server side, ASPxHttpHandlerModule automatically catches the exception and passes an error message to the client. This message may contain details about the exception or a generic error message. The message displayed depends on the mode attribute setting within the Web.config file’s <customErrors> section. This attribute affects message text in the following manner.

On - Generic (custom) error text is shown to remote clients and to the local host. This text can be localized, and is defined by the ASPxperienceStringId.CallbackGenericErrorText constant.
Off - Detailed ASP.NET errors are shown to remote clients and to the local host.
RemoteOnly - Generic (custom) error text is shown only to remote clients, and detailed ASP.NET errors are displayed on the local host.

Regardless of the customErrors section’s mode setting, you can use one of the following approaches to modify the error message to be sent to the client.

Component Level
Handle a DevExpress component’s CustomErrorText event, if any. Some DevExpress MVC extensions provide this event (such as FileManager’s FileManagerSettings.CustomErrorText and Scheduler’s SchedulerSettings.CustomErrorText) .
Application Level
Alternatively, you can use the static ASPxWebControl.SetCallbackErrorMessage method to handle errors at the application level.

Handling Callback Exceptions

View Example: How to handle application-level errors occurred during callbacks

On the Client Side

A DevExpress ASP.NET Ajax-enabled component automatically catches server exceptions that occur within its server-side event handler, and passes corresponding error information to the client for processing. On the client side, use the component’s CallbackError client event to process the error at the component level, or handle the MVCxGlobalEvents extension’s MVCxClientGlobalEvents.CallbackError client event to process the error globally (across all DevExpress MVC web component).

Handle either of these client events to perform specific client-side actions, such as to display explanatory text or an image related to the error.

This example demonstrates how to use the Spreadsheet ‘s CallbackError client event to process a server error.

Razor

razor

@Html.DevExpress().Spreadsheet(settings => {
    settings.Name = "Spreadsheet";
    settings.ClientSideEvents.CallbackError = "OnCallbackError";
    settings.PreRender = (s, e) => {
        // ...
        throw new Exception("A new exception.");
    };
}).GetHtml()

javascript

function OnCallbackError(s, e) {
    e.handled = true;
    alert('The CallbackError event is raised: ' + e.message;
}

On the Server Side

You can use the static ASPxWebControl.CallbackError server event to delegate callback exception handling to the Application_Error event handler (via the web application project’s Global.asax file), so that it handles all application-level errors (e.g., to log information on all errors). In the Global.asax file, add the following code to the Application_Start event handler.

C#
VB.NET

csharp

void Application_Start(object sender, EventArgs e) { 
    // Assign Application_Error as a callback error handler for DevExpress web controls
    ASPxWebControl.CallbackError += new EventHandler(Application_Error); 
}

Protected Sub Application_Start(ByVal sender As Object, ByVal e As EventArgs)
    AddHandler DevExpress.Web.ASPxWebControl.CallbackError, AddressOf ASPxWebControl_CallbackError
End Sub

Use the following code within the Application_Error event handler to obtain and log exception details:

C#
VB.NET

csharp

void Application_Error(object sender, EventArgs e) { 
    // ... 
    // Use HttpContext.Current to get a Web request processing helper 
    HttpServerUtility server = HttpContext.Current.Server; 
    Exception exception = server.GetLastError(); 
    // Log an exception 
    AddToLog(exception.Message, exception.StackTrace); 
}

Private Sub ASPxWebControl_CallbackError(ByVal sender As Object, ByVal e As EventArgs)
    ' ...  
    ' Use HttpContext.Current to get a Web request processing helper  
    Dim server As HttpServerUtility = HttpContext.Current.Server
    Dim exception As Exception = server.GetLastError()

    ' Log an exception  
    AddToLog(exception.Message, exception.StackTrace)
End Sub

Response Redirection on Callback Exceptions

When an unhandled exception occurs during server-side callback processing, ASPxHttpHandlerModule prevents an application from becoming unresponsive by sending a specific response to the client. Specify the required page name in the Web.config file’s callbackErrorRedirectUrl option to redirect the response to a page that displays error information – as shown below.

xml

<configuration>
  ...
  <devExpress>
    ...
    <errors callbackErrorRedirectUrl="/Errors/Error.cshtml" />
  </devExpress>
</configuration>

Note that the callbackErrorRedirectUrl property value should contain the subdirectory name (if required) and use the following format: /subdir/Home/Error

Note

For MVC apllications, the callbackErrorRedirectUrl property value should contain a subdirectory name (“/{sub-directory}/Home/Error”) if the MVC application’s root URL meets the following conditions:

The URL is overridden by the IIS Web Server.
The URL contains a subdirectory (for example, “http://localhost/{sub-directory}”).

Typically, the page to which the response is redirected shows information about the server exception. Use the static ASPxWebControl.GetCallbackErrorMessage method while the page redirect is processed, to obtain exception-related information. For example, you can execute the code below on page load.

C#
VB.NET

csharp

using DevExpress.Web;

public partial class Error : Page {
    protected void Page_Load(object sender, EventArgs e) {
        string errorMessage = ASPxWebControl.GetCallbackErrorMessage();
        Response.Output.Write(errorMessage);
    }
}

Imports DevExpress.Web

Public Partial Class [Error]
    Inherits Page
    Protected Sub Page_Load(ByVal sender As Object, ByVal e As EventArgs)
        Dim errorMessage As String = ASPxWebControl.GetCallbackErrorMessage()
        Response.Output.Write(errorMessage)
    End Sub
End Class