Error Handling in ASP.NET and Mobile Applications

This topic demonstrates error handling mechanisms used in ASP.NET and Mobile applications and explains how to customize them.

This topic contains the following sections:

Error Messages on the Current Page (ErrorInfoControl)

In XAF ASP.NET Web applications, an exception can be raised as a result of executing an Action. In this case, there is no need to load an error page, which could confuse the end-user. Instead, the eXpressApp Framework provides the ErrorInfoControl control displayed on the current page. All the Web Templates contain this control, but it is initially invisible. When an exception is raised in an Action's event handler, the system that handles exceptions makes this control visible, and displays the error description in it.

The following image illustrates the ErrorInfoControl on a page with the failed Action.

ErrorHandlingExceptionOnAction

After this, an end-user can continue working with the application.

You can also use this ErrorInfoControl to manually provide information on non-critical errors. For this purpose, call the ErrorHandling.SetPageError method, which takes the required exception as a parameter. For example, built-in Action Containers call this method when an exception is raised while executing an Action from their Action collections.

public static class ActionExceptionHandler {
    public static void HandleException(HandleExceptionEventArgs e) {
        if(!e.Handled) {
            ErrorHandling.Instance.SetPageError(e.Exception);
            e.Handled = true;
        }
    }
}
// ...
public class ActionContainerHolder : Panel, INamingContainer {
// ...
    private void action_ExecutionException(object sender, HandleExceptionEventArgs e) {
        ActionExceptionHandler.HandleException(e);
    }
// ...
}

In the code above, the ErrorHandling is a class that is used to handle errors occurring in ASP.NET applications.

Note

You can handle the ErrorInfo.FormatText static event to provide a custom text for an XAF standard error message.

Error Messages on Error Pages

Errors that are not reported via the ErrorInfoControl (defined above) are reported on error pages. Error pages are shown by the Application_Error method implemented in the Web Application project's Global.asax.cs (Global.asax.vb) file. This method invokes the ErrorHandling.ProcessApplicationError method, which performs the following.

  • Sends Notification to the Application Administrator

    Error description and the corresponding section from the log file are sent by e-mail to recipients specified in the Web.config file. Available e-mail settings are listed in the end of this topic.

    By default, the collected information on an error is sent using the Simple Mail Transfer Protocol (SMTP). If you need to use another notification delivery mechanism (e.g., instant messaging), handle the ErrorHandling.CustomSendErrorNotification event, implement delivery of notifications and set the handler's Handled parameter to true. If you accept using SMTP, but need to customize message options (e.g., provide SMTP credentials), use the <smtp> element, or handle the ErrorHandling.CustomSendMailMessage event. Moreover, you can send the message yourself in your handler. In this instance, set the Handled parameter to true.

  • Writes Exception to Log File

    Information on the occurred exception is logged.

  • Displays Error Page

    Normally, the Error.aspx page specified by the RichErrorReportPage setting is loaded. This page provides the error description and possible steps to be performed by an end-user. In addition, if the application was run locally, or the user IP was specified by the DetailedErrorReaderIp setting, then this error page would contain detailed information on the error and the corresponding section of the log file. The error page can also include an editor that allows end-users to post additional information to application administrators. The editor is not displayed if e-mail settings are not configured.

    If the error has occurred when you start the application, or the error page is not specified by the RichErrorReportPage setting, an HTML page with an error message is generated. You can specify a custom HTML page to be loaded in this situation. For this purpose, set the SimpleErrorReportPage setting to the custom page. The {REQUESTURL} and {DETAILS} parameters are allowed in this key's value. These parameters will be substituted with the request URL and error details respectively.

The following diagram illustrates the error handling mechanism.

ErrorHandling

The following image demonstrates the default simple error page.

ErrorHandlingSimpleErrorPage

The following image demonstrates the default rich error page.

ErrorHandlingErrorPage

Configuration File Keys Related to the Error Handling

Key Name Sample Value Description
ErrorReportEmail admin@example.com Specifies the e-mail address the error notifications will be sent to. You can provide several addresses, separated by semicolons. If omitted, the notifications are not sent.
ErrorReportEmailServer smtp.example.com Specifies the SMTP server used to deliver notifications. If the server requires authentication, follow the instructions from the ErrorHandling.CustomSendMailMessage topic. You can also omit this key. Settings from the <smtp> element will be used in this instance.
ErrorReportEmailFrom application@example.com Specifies the e-mail address the error notifications will be sent from. If omitted, the "null@nospam.com" address is used.
ErrorReportEmailFromName {0:ApplicationName} errors Specifies the name to be used in the "From" field of the notification. You can use the ApplicationName and ExceptionMessage parameters. These parameters will be substituted with the application name and exception message respectively. If omitted, the "{0:ApplicationName} Error handling system" text is used.
ErrorReportEmailSubject The '{0:ExceptionMessage}' error occurs. Specifies the text to be used as the notification subject. You can use the ApplicationName and ExceptionMessage parameters. These parameters will be substituted with the application name and exception message respectively. If omitted, the "{0:ExceptionMessage}" text is used.
ErrorReportEnableSsl True Specifies if the SMTP connection is encrypted. The "True" and "1" values enable encryption, any other values – disable it. If omitted, the encryption is not used. This key value is ignored if the ErrorReportEmailServer value is not specified.
SimpleErrorReportPage simpleerrorreport.html Specifies the URL of a custom web page whose content will be shown as a simple error report. The simple error report is shown when the error occurs upon the starting of an application, or if the rich error report content is not specified. The {REQUESTURL} and {DETAILS} strings will be substituted with the request URL and error details respectively. The error details are visible if the request is local by default. If omitted, the default content is generated.
RichErrorReportPage richerrorreport.html Specifies the URL of a custom web page whose content will be shown as a rich formatted error report. The rich error report is shown when the error occurs while at run time. The {REQUESTURL} and {DETAILS} strings will be substituted with the request URL and error details respectively. The error details are visible by default if the request is local. The "Error.aspx" page is specified in the default Web.config file. If omitted, the simple error report is shown.
DetailedErrorReaderIp 192.168.0.101 Specifies the IP address of the remote host, which is allowed to get the detailed error information (including trace entries). If omitted, the error details are displayed for local requests only.

These settings should be specified in the appSettings section of the Web.config file.

<appSettings>
    <add key="ErrorReportEmail" value="admin@example.com" />
    <add key="ErrorReportEmailFrom" value="application@example.com" />
    <add key="ErrorReportEmailServer" value="smtp.example.com" />
    <add key="SimpleErrorReportPage" value="" />
    <add key="RichErrorReportPage" value="Error.aspx" />
    <!-- ... -->
</appSettings>

Error Messages on the Current Page (dxToast)

In an XAF Mobile application, an exception can be raised when an Action or JS-script is executed, or when data is requested. This exception is displayed as a user-friendly message by the Toast widget. The following image demonstrates the exception raised when logging in with a nonexistent username or incorrect password.

ErrorHandling_Mobile

This message can be closed manually by clicking on it; otherwise, it is closed automatically after a certain time. This message does not stop the application execution - an end-user can continue working with the application.

Note

Information on the exception is logged.

You can also show the custom error message from the client-side code using the DevExpress.ui.notify method. The ActionBaseExtensions.RegisterClientScriptOnExecute topic demonstrates how to use this method to display a text message when an Action is executed.