Configuring Custom Error Messages in IIS 5.0

By Ram Papatla, Microsoft IIS Documentation Team

The examples in this article demonstrate the Custom Error feature for 404 errors.

Introduction

After spending many long hours building your Web application, you still need to make frequent updates to the content and site layout. You try to ensure that all the old links to your sites have pointers to the new/updated links. But what about the ones you have missed or a case where the pages expire? Yes, your users will see the most notorious HTTP error code:

404 Not Found 
The Web server cannot find the file or script you asked for. Please check the URL
to 
ensure that the path is correct. 
Please contact the server's administrator if this problem persists.

By reviewing the IIS logs at a later time, you can identify these errors and take necessary actions to fix them. Also, the Performance Monitor application allows you to monitor and set alerts on various counters. You can use the Web Service\ Not Found Errors/sec counter to track the rate at which not found errors are occurring on your server and set alerts to notify the Administrator when the rate of not-found errors exceeds a threshold.

What about the user who encounters the errors? They are not very pleased with the generic uninteresting HTTP error codes. Fortunately, IIS provides a way to define custom content at the time these errors occur: The Custom Error Messages feature in IIS. With this feature a Web site administrator can define a template that will be invoked when a user encounters an HTTP error. Although, this article will talk about customizing the HTTP 404 error message, a similar procedure can be used to tackle other HTTP errors. Custom Error Messages can be defined for the entire www level, per Web site, or per virtual directory level and it can map to a file or to a URL, and it can be implemented by using the Custom Errors property sheet in the IIS snap-in.

Custom Error pages can include the style sheets, images, and standard headers and footers employed by other pages of your Web site. This will help the error page look similar to the other pages of the site, and the user can easily navigate from the error page.

Configuration

Please keep in mind that if you are using static custom error files (HTML files), you should always use map to a file. If you plan to develop an application (using ISAPI or ASP) to handle errors, then use map to a URL.

To customize an error message by mapping to a file

  1. Create a file that contains your custom error message, and place it in a directory.

  2. In the Internet Information Services snap-in, select the Web site, virtual directory, directory, or file you would like to customize HTTP errors, and then click Properties.

  3. Select Custom Errors.

  4. Select the HTTP error that you would like to change, in this case 404.

  5. Click Edit Properties.

  6. Select File from the drop-down list.

  7. Enter the full path that points to your customized error message, or use Browse... to locate the file on your computer's hard disk.

  8. Click OK.

To customize an error message by mapping to a URL

  1. Create a file that contains your custom error message, and place it in a directory.

  2. In the Internet Information Services snap-in, select the Web site, virtual directory, directory, or file you would like to customize HTTP errors, and then click Properties.

  3. Select Custom Errors.

  4. Select the HTTP error that you would like to change, in this case 404.

  5. Click Edit Properties.

  6. Select URL from the drop-down list.

  7. Type the URL, that points to your customized error message by entering the path to the URL beginning with the virtual directory name. If the file is present on the root of your Web site, you don't need to enter a virtual directory name.

  8. Click OK.

Implementation

Mapping to a File

Let us see how we can implement mapping to file. Create a page and name it handle404.htm and save it in the root directory of your Web site. Using the mapping to a file instructions mentioned in the configuration section, configure the custom 404 message of your Web site to point to the file, handle404.htm. Note: you must enter the full path to the file handle404.htm.

In the HTML file, handle404.htm, copy the following HTML code to display to the user when a HTTP 404 error occurs:

<HTML>
<HEAD>
<TITLE>Sorry, your requested page was not found on reskit.com</TITLE >
</HEAD>
<BODY>
The page you requested, was not found on reskit.com<br>
It's possible you typed the address incorrectly, or that the page no 
longer exists. <br>
As an option, you may visit any of the pages below for information about 
our services or products:<BR>
Our Home Page<BR>
Our Search Page<BR>
Our Products Page
</BODY>
</HTML>

When a user encounters a HTTP 404 error, the file handle404.htm is called, and the HTML content is displayed. Although, the file does not accomplish much, it is better than showing the nasty generic HTTP 404 error.

Mapping to a URL

Mapping to a file does a very good job of replacing the nasty generic HTTP error. What if you wanted to create an application to handle these errors and do more than just showing a graceful error page, for example: sending an email alert to the administrator as soon as this error occurs?

Mapping to a URL is different from the file method in handling the HTTP error. If a 404 error occurs when mapping to a URL, the script is invoked as a URL, which passes context as part of the query string. For example, if you have an .asp file called Handle404.asp, which is defined to handle HTTP 404 errors. When a user tries to access a file that does not exist on your server, say a file called missing.htm, then the ASP file will be invoked as if the user had typed:

https://www.reskit.com/handle404.asp?404;https://www.reskit.com/missing.htm

in the Web browser.

With the information from the above query string, "404;https://www.reskit.com/missing.htm", we can show the user the page they have requested, and send instant notification to the administrator. Let us see how this can be done.

We will now implement mapping to a URL. Create a page and name it handle404.asp and save it in the root directory of your Web site. Using the mapping to a URL instructions mentioned in the configuration section, configure the custom 404 message of your Web site to point to the URL, handle404.asp. Note: since the file resides on the root of your Web site, you must enter "/handle404.asp" for the path of the URL.

In the ASP file handle404.asp, we will write code to capture the query string with the help of Request.query string. We will then clean the captured query string to get the requested URL and send a mail to the Web site administrator using CDONTS (For more information on CDONTS, please refer to https://support.microsoft.com/default.aspx?scid=kb;en-us;186204&sd=tech ). After all the server side processing is complete, we will display the page to the user.

In the ASP file, handle404.asp, copy the following code to display to the user when a HTTP 404 error occurs:

<%@Language="VBScript" %>
<%
'handle404.asp – ASP file for handling Customer Error
'Messages mapped to a URL
Dim capturedQryStrg
Dim requestedURL
'As I explained above, the entire query string starts with
'the error number, followed by the requested URL
capturedQryStrg = Request.ServerVariables("Query_String")
'Once we have captured the entire query string, in this
'case "404;https://www.reskit.com/missing.htm", let us
'clean it by removing the "404;", leaving us with just the
'requested URL
requestedURL = Replace(capturedQryStrg, "404;", "")
'After we are done with cleaning up, we will send a mail
'to the web site administrator using the CDONTS object.
'We will mark the email as urgent.
Dim errMail
Set  errMail = Server.CreateObject("CDONTS.NewMail")
errMail.From = "webuser@reskit.com"
errMail.To = "webmaster@reskit.com"
errMail.Subject = "URGENT - 404 Error"
errMail.Body = "User requested - " & requestedURL
errMail.Importance = 2
errMail.Send
Set errMail = Nothing
'We are done with the server-side processing.
'We will now display the content to the user.
%>
<HTML>
<HEAD>
<TITLE>Sorry, but <% = requestedURL %> was not found on reskit.com</TITLE >
</HEAD>
<BODY>
The page you requested, <%= requestedURL %>was not found on 
reskit.com<br>
It's possible you typed the address incorrectly, or that the page no 
longer exists. <br> 
An email alert has been sent to the administrator regarding this 
error.<BR>
As an option, you may visit any of the pages below for information about 
our services or products:<BR>
Our Home Page<BR>
Our Search Page<BR>
Our Products Page
</BODY>
</HTML>

If a user encounters a HTTP 404 error in this case, we are able to replace the nasty HTTP 404 error. This page also shows the requested URL and email is immediately sent to alert to the administrator.

Conclusion

The Custom Error Message feature is useful to replace the generic HTTP errors on your Web site, at the time a user encounters them. You can also employ the same look and feel and navigation abilities in the error pages. The examples mentioned in this article are simplified to demonstrate the Custom Error feature for 404 errors. They can be easily extended to handle most other HTTP errors and modified to take immediate action, like sending administrative alerts.