Microsoft ASP.NET QuickStarts Tutorial

Handling Errors

   Customizing Error Pages
   Handling Errors Programmatically
   Writing to the Event Log
   Section Summary

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 Error1.aspx

[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:

<configuration>
     <system.web>
         <customErrors defaultRedirect="genericerror.htm" mode="remoteonly" />
     </system.web>
</configuration>

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="VB" Description="Error page"%>

<html>
<head>
<title>Error page</title>
</head>

<body>
<h1>Error page</h1>
Error originated on: <%=Request.QueryString("ErrorPage") %>
</body>
</html>

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.

Attribute Description

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.

Mode Local 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 Custom1.aspx

[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:

<configuration>
  <system.web>
    <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"/>
    </customErrors>
  </system.web>
</configuration>

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

Attribute Description

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 Custom1.aspx

[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">

Sub Page_Error(Source As Object, E As EventArgs)
    Dim message As String = "<font face=verdana color=red>" _
                           & "<h4>" & Request.Url.ToString() & "</h4>" _
                           & "<pre><font color='red'>" & Server.GetLastError().ToString() & "</pre>" _
                           & "</font>"

    Response.Write(message)
End Sub

</script>

The following sample demonstrates the Page_Error method.

VB Error2.aspx

[Run Sample] | [View Source]

You could do something useful in this method, like sending an e-mail to the site administrator saying that the page failed to execute properly. ASP.NET provides a set of classes in the System.Web.Mail namespace for just this purpose. To import this namespace, use an @Import directive at the top of your page, as follows:

<%@ Import Namespace="System.Web.Mail" %>

You can then use the MailMessage and SmtpMail objects to programmatically send e-mail.


Dim mail As New MailMessage
mail.From = "automated@yourservername.com"
mail.To = "administrator@yourservername.com"
mail.Subject = "Site Error"
mail.Body = message
mail.BodyFormat = MailFormat.Html
SmtpMail.Send(mail)

The following sample shows how to send a mail message in response to a page error.

Note: This sample does not actually send mail unless you have configured the SMTP mail service on your machine. For more information about the SMTP mail service, consult the IIS documentation.

VB Error3.aspx

[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.


Sub Application_Error(sender As Object, e As EventArgs)
    '...Do something here
End Sub

Writing to the Event Log

The System.Diagnostics namespace provides classes for writing to the Windows event log. To use this namespace in your pages, you must first import the namespace, as follows:

<%@ Import Namespace="System.Diagnostics"%>

The EventLog class encapsulates the log itself. It provides static methods for detecting or creating logs and can be instantiated to write log entries from code. The following example shows this functionality within the Application_Error method of Global.asax. Whenever an unhandled exception occurs in the application, an entry containing the error message and stack trace is made to the application log.


Sub Application_Error(sender As Object, e As EventArgs)

     Dim Message As String = "\n\nURL:\n http://localhost/" & Request.Path _
                                       & "\n\nMESSAGE:\n " & Server.GetLastError().Message _
                                       & "\n\nSTACK TRACE:\n" & Server.GetLastError().StackTrace

    ' Create event log if it does not exist

     Dim LogName As String = "Application"
     If (Not EventLog.SourceExists(LogName))
        EventLog.CreateEventSource(LogName, LogName)
     End If

     ' Insert into event log
     Dim Log As New EventLog
     Log.Source = LogName
     Log.WriteEntry(Message, EventLogEntryType.Error)

End Sub

The complete source code for the preceding example follows. Note that this code is disabled so that it cannot run here, to prevent entries to your Windows event log. If you would like to see this code run, create an IIS virtual root pointing to the directory that contains this file.

VB Global.asax

[View Source]

Section Summary

Errors are divided into four categories: configuration errors, parser errors, compilation errors, and run-time errors.
By default, the information shown for a run-time error is the call stack (the chain 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.
ASP.NET enables you to specify whether errors are shown to local clients, to remote clients, or to both. By default, errors are only shown to local clients (clients on the same computer as the server). You can also specify a custom error page to redirect clients to if an error occurs.
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 for associating HTTP status codes with custom error pages.
You can also handle errors in code, at either the page level or application level. The Page base class exposes a HandleError method, which you can override in your pages. The method will be called whenever an uncaught exception is thrown at run time.
The System.Web.Mail namespace exposes classes for programmatically sending e-mail. This is useful for notifying an administrator when an error occurs.
In addition to handling errors at the page level, you can use the Application_Error event in Global.asax to handle errors at the application level. This event will occur for any unhandled exception thrown within the application.
The System.Diagnostics namespace provides classes for writing to the Windows event log.