Home   |   QuickStart Welcome   |   ASP.NET   |   Web Services   |   How Do I...?   
  |   I want my samples in...      

ASP.NET 2.0 Quickstart Tutorials

Handling Errors

When an error occurs on a page, ASP.NET sends information about the error to the client. Errors are divided into four categories:
  • Configuration errors: Occur when the syntax or structure of a Web.config file in the configuration hierarchy is incorrect.
  • Parser errors: Occur when the ASP.NET syntax on a page is malformed.
  • Compilation errors: Occur when statements in a page's target language are incorrrect.
  • Run-time errors: Occur during a page's execution, even though the errors could not be detected at compile time.
By default, the information shown for a run-time error is the call stack (the chains of procedure calls leading up to the exception). If debug mode is enabled, ASP.NET displays the line number in source code where the run-time error originated. Debug mode is a valuable tool for debugging your application. You can enable debug mode at the page level, using the following directive:
<%@ Page Debug="true" %>
You can also enable debug mode at the application level, using the Web.config file in the application's root directory, as shown in the following example.

Note: Running debug mode incurs a heavy performance penalty. Be sure to disable it before deploying your finished application.

The following example demonstrates the use of debug mode to show source line numbers for a run-time exception.

VB Debug Mode
Run Sample View Source

Customizing Error Pages

Depending on the circumstances, you might want to handle application errors in different ways. For example, at development time you probably want to see the detailed error pages that ASP.NET provides to help you identify and fix problems. However, once an application is being served in a production environment, you probably do not want to display detailed errors to your customer clients. You can use ASP.NET to specify whether errors are shown to local clients, to remote clients, or to both. By default, errors are shown only to local clients (those clients on the same computer as the server). You can also specify a custom error page to redirect clients to if an error occurs.

Custom errors are enabled in the Web.config file for an application. For example:
         <customErrors defaultRedirect="genericerror.htm" 
             mode="RemoteOnly" />
This configuration enables local clients to see the default ASP.NET detailed error pages but redirects remote clients to a custom page, genericerror.htm. This page could be an .aspx page as well. ASP.NET passes the path of the page on which the error occurred to the error page as a QueryString argument. Note that if the execution of the error page generates an error, a blank page is sent back to the remote client.

<%@ Page Language="C#" Description="Error page"%>

<title>Error page</title>

<h1>Error page</h1>
Error originated on: <%=Request.QueryString["ErrorPage"] %>

Note: Only files mapped to the aspnet_isapi.dll extension in IIS generate these errors. Files not served through the aspnet_isapi.dll are not processed by ASP.NET and generate IIS errors. See the IIS documentation for information about configuring IIS custom errors.

The following table describes the configuration attributes and values for the <customErrors> tag.

mode Indicates whether custom errors are enabled, disabled, or only shown to remote computers. Values: On, Off, RemoteOnly (default).
defaultRedirect Indicates the default URL to which a browser should be redirected if an error occurs. This attribute is optional.

The Mode attribute determines whether errors are shown to local clients, remote clients, or both. The effects of each setting are described in the following table.

ModeLocal host request Remote host request
On Custom error page. Custom error page.
Off ASP.NET error page. ASP.NET error page.
RemoteOnly ASP.NET error page. Custom error page.

The following sample demonstrates how the <customErrors> configuration section is used.

VB Custom Errors
Run Sample View Source

In addition to redirecting to a common page for all errors, you can also assign specific error pages to specific error status codes. The <customErrors> configuration section supports an inner <error> tag that associates HTTP status codes with custom error pages. For example:
    <customErrors mode="RemoteOnly" defaultRedirect="/genericerror.htm">
      <error statusCode="500" redirect="/error/callsupport.htm"/>
      <error statusCode="404" redirect="/error/notfound.aspx"/>
      <error statusCode="403" redirect="/error/noaccess.aspx"/>
The following table describes the attributes and values for the <error> tag.

StatusCode HTTP status code of errors for which the custom error page should be used. Examples: 403 Forbidden, 404 Not Found, or 500 Internal Server Error.
Redirect URL to which the client browser should be redirected if an error occurs.

The following example demonstrates how to use the <error> tag. Note that the example specifies an .aspx page for "File Not Found" errors so that the missing page URL passed via the QueryString can be printed.

VB Error Tag
Run Sample View Source

Handling Errors Programmatically

You can also handle errors in code, at either the page level or the application level. The Page base class exposes a Page_Error method, which you can override in your pages. The method is called whenever an uncaught exception is thrown at run time.

<script language="C#" runat="server">

void Page_Error(Object source, EventArgs e) {
    String message = "<font face=verdana color=red>"
        + "<h4>" + Request.Url.ToString() + "</h4>"
        + "<pre><font color='red'>" 
        + Server.GetLastError().ToString() + "</pre>"
        + "</font>";



The following sample demonstrates the Page_Error method.

VB Page_Error Method
Run Sample View Source

In addition to handling errors at the page level, you might want to handle errors at the application level. To do this, use the Application_Error event in Global.asax. This event occurs for any unhandled exception thrown within the application.

void Application_Error(Object sender, EventArgs e) {
    //...Do something here