Custom Error Pages in ASP.NET

Introduction

ASP.NET applications are configured with web.config files which are standard xml files that can be opened and modified in any text editor. The web.config files can be used to specify settings for every ASP.NET app on a machine, a particular ASP.NET application, ASP.NET pages in a specific directory, or just a single ASP.NET page. For the purpose of this article the web.config file will apply to just a single asp.net application.

The web.config file has several sections that contain the configuration settings that affect ASP.NET applications. The following is a partial list of sections in a web.config file. Also, note that the web.config file is case sensitive.

authentication - This section specifies how the authenthication mode for an asp.net application
browserCaps - This section lists information on the capabilities of different browsers.
compilation - This section contains the information for compiling pages. The default language to use for compiling pages can be set and choices include C#, VB.NET or JScript.Net. This section also includes information about whether the pages should be compiled in debug mode.
customErrors - This section specifies how error information is handled.
sessionState - The information about session state is kept here.
trace - This section has the information about page and application tracings.

Custom Errors

The portion of the web.config file that we are concerned with today is the customErrors section. The customErrors section consists of a tag like the following:

The attribute mode enables or disables custom errors. When the custom error mode is enabled, error pages are hidden. This setting has 3 possible values: On, Off, and RemoteOnly. The customErrors tag must be placed within <system.web> tags.

You can use custom errors to to hide errors from user of your web site and then present them with a more friendly error message. When the custom error more is set to On, detailed error information is hidden. When the custom error mode is assigned the value Off, all available error information is displayed. Lastly, if custom errors is set to remoteOnly, errors are hidden when the page is requested by a browser on a remote machine, but the errors are displayed when the page is requested by a browser on the same machine as the web server. If you need to view detailed error information, you need to disable custom errors, or set it to remoteOnly. The custom errors mode is configurable in the web.config file for a specific application. The following 3 code samples demonstrate the 3 different setting for custom errors.

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
   <system.web>
     <customErrors mode="Off" />
   </system.web>
</configuration>

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
   <system.web>
     <customErrors mode="On" defaultRedirect="apperror.aspx"/>
   </system.web>
</configuration>

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
   <system.web>
     <customErrors mode="RemoteOnly" defaultRedirect="apperror.aspx"/>
   </system.web>
</configuration>

When customErrors is set to On or RemoteOnly, you need to specify the defaultRedirect attribute. This attribute contains the error page to which the user will be redirected. Additionally you can take custom error handling a step further by associating specific errors with specific error pages. The customErrors section can contain error elements that associate particular errors with error pages. The following code sample illustrates this concept.

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
   <system.web>
     <customErrors mode="RemoteOnly" defaultRedirect="apperror.aspx"/>
     <error statusCode="404" redirect="404.aspx" />
     <error statusCode="500" redirect="500.aspx" />
   </system.web>
</configuration>

In the above code, 404-Page Not Found errors are associated with 404.aspx while 500-InternalServer Errors are associated with 500.aspx. Finally, the defaultRedirect attribute associates any other error with the apperror.aspx page.

If you request a page and that page does not exist on the web server, you are automatically redirected to 404.aspx.

Emailing the webmaster

Using an asp.net page to display custom error messages means that you can add a subroutine that will fire on Page_Load. A good use for this subroutine is to email the webmaster about the error.

When you are redirected to a page with custom errors, a querystring variable is automatically passed to the error page. The query string variable, named aspxerrorpath, contains the path of the page that was originally requested. The path of the requested page can be found by using Request.Params("aspxerrorpath"). You can then use this value in an email to the webmaster informing him or her of the page error and which page caused the error. The following VB.NET code illustrates this idea.

Sub Page_Load(sender As System.Object, e As System.EventArgs)
Dim ObjMM As New MailMessage()
Dim ErrorUrl As String = Request.Params("aspxerrorpath").ToString
   ObjMM.From = "support@mysite.com"
   ObjMM.To = "webmaster@mysite.com"
   ObjMM.Subject = "Site Error"
   ObjMM.Body = "An error has occurred on mysite.com. A user requested      the page " & ErrorUrl & ". "
   ObjMM.BodyFormat = MailFormat.Text
   SmtpMail.SmtpServer = "mail.mysite.com"
   SmtpMail.Send(ObjMM)
End Sub

The above code sends an email to the webmaster anytime the error page loads. The body of the email contains a message stating an error has occured and indicates what page triggered the error. This code block must be placed within <script></script> tags and the runat attribute of the <script> tag must be set to server.

Conclusions

In this tutorial we have looked at how the web.config file allows you to set up custom error messages for you asp.net applications. We looked at how you can associate specific error codes with different error pages. We also examined how you can email the webmaster about the error message. I have also two useful links below that discuss sending email in asp.net in more detail.