How To Use the ASPError Object to Build a Custom Error-Handling Page in Internet Information Server (299981)


The information in this article applies to:

  • Microsoft Active Server Pages
  • Microsoft Internet Information Server 5.0
This article was previously published under Q299981

IN THIS TASK

SUMMARY

This step-by-step guide demonstrates how to use the new ASPError object to create a custom, centralized error-handling page. For example, your application may require that someone be sent an e-mail notification when an error has occurred and some process in the system has not completed. Or, you may want to log some information to a database in addition to the Internet Information Server (IIS) error log information. For information on how to do this, see the "Error Reporting - IIS 5.0" article in the "References" section.

back to the top

Prerequisites

  • Microsoft Windows 2000 Professional, Windows 2000 Server, or Windows 2000 Advanced Server
  • Internet Information Server 5.0 installed and configured
The ASPError object and the related Active Server Pages (ASP) methods that are required to use the ASPError object are new to Active Server Pages 3.0 (ASP) and are not available on pre-Windows 2000 operating systems.

back to the top

Create a New SubWeb

  1. Right-click Start, and then click Explore to open Windows Explorer.
  2. Select the root folder of your Web site (which is C:\InetPub\Wwwroot by default).
  3. On the File menu, point to New, and then click Folder. Name the folder ErrTest.
  4. Right-click ErrTest, and then click Properties.
  5. On the Security tab, click Everyone. Under Permissions, make sure that the Read and Write check boxes are selected. Leave the other check boxes as they are. If you make any changes, click Apply.
  6. From the Windows Start menu, point to Programs, point to Administrative Tools, and then click Internet Services Manager to open the Internet Services Manager (ISM).
  7. Under the Default Web Site, you should see the ErrTest directory. Right-click ErrTest, and then click Properties.
  8. Confirm that Anonymous access is enabled as follows:
    • On the Directory Security tab, under Anonymous Access and Authentication control, click Edit.
    • Select the Anonymous Access check box, click OK, and then click Apply.
  9. To mark the directory as an ASP application, on the Directory tab, click Create under Application Settings. Click Apply to save your changes, and click OK to close the ErrTest Properties dialog box.
back to the top

Create a Custom Error-Handling ASP Page

  1. From the Windows Start menu, point to Programs, point to Accessories, and then click Notepad.
  2. Paste the following code into Notepad to create a sample ASP error-handler page:
    <%@Language="VBSCRIPT"%>
<%
 Option Explicit
 On Error Resume Next
 Response.Clear
 Dim objError
 Set objError = Server.GetLastError()
%>
<html>
<head>
<title>ASP 500 Error</title>
<style>
BODY  { FONT-FAMILY: Arial; FONT-SIZE: 10pt;
	   BACKGROUND: #ffffff; COLOR: #000000;
	   MARGIN: 15px; }
H2    { FONT-SIZE: 16pt; COLOR: #ff0000; }
TABLE { BACKGROUND: #000000; PADDING: 5px; }
TH    { BACKGROUND: #0000ff; COLOR: #ffffff; }
TR    { BACKGROUND: #cccccc; COLOR: #000000; }
</style>
</head>
<body>

<h2 align="center">ASP 500 Error</h2>

<p align="center">An error occurred processing the page you requested.<br>
Please see the details below for more information.</p>

<div align="center"><center>

<table>
<% If Len(CStr(objError.ASPCode)) > 0 Then %>
 <tr>
   <th nowrap align="left" valign="top">IIS Error Number</th>
   <td align="left" valign="top"><%=objError.ASPCode%></td>
 </tr>
<% End If %>
<% If Len(CStr(objError.Number)) > 0 Then %>
 <tr>
   <th nowrap align="left" valign="top">COM Error Number</th>
   <td align="left" valign="top"><%=objError.Number%>
   <%=" (0x" & Hex(objError.Number) & ")"%></td>
 </tr>
<% End If %>
<% If Len(CStr(objError.Source)) > 0 Then %>
 <tr>
   <th nowrap align="left" valign="top">Error Source</th>
   <td align="left" valign="top"><%=objError.Source%></td>
 </tr>
<% End If %>
<% If Len(CStr(objError.File)) > 0 Then %>
 <tr>
   <th nowrap align="left" valign="top">File Name</th>
   <td align="left" valign="top"><%=objError.File%></td>
 </tr>
<% End If %>
<% If Len(CStr(objError.Line)) > 0 Then %>
 <tr>
   <th nowrap align="left" valign="top">Line Number</th>
   <td align="left" valign="top"><%=objError.Line%></td>
 </tr>
<% End If %>
<% If Len(CStr(objError.Description)) > 0 Then %>
 <tr>
   <th nowrap align="left" valign="top">Brief Description</th>
   <td align="left" valign="top"><%=objError.Description%></td>
 </tr>
<% End If %>
<% If Len(CStr(objError.ASPDescription)) > 0 Then %>
 <tr>
   <th nowrap align="left" valign="top">Full Description</th>
   <td align="left" valign="top"><%=objError.ASPDescription%></td>
 </tr>
<% End If %>
</table>

</center></div>

</body>
</html>
  3. On the File menu, click Save. When you are prompted, name the page My500ErrHandler.asp, and save the page to the ErrTest folder that you created earlier.
back to the top

Set the New Page as the Error Handler for 500-Type Errors

  1. On the Start menu, point to Programs, point to Administrative Tools, and then click Internet Services Manager.
  2. Right-click the ErrTest virtual directory under the Default Web Site, and then click Properties.
  3. On the Custom Errors tab, scroll down to an entry that includes "500;100" in the HTTP Errors column. This is where you change the setting to point to your custom error handler.
  4. Select the line that is the current definition for 500;100 errors, and then click Edit Properties.
  5. In the Message Type drop-down list box, click URL.
  6. In the URL text box, notice that it points to the page at "/iisHelp/common/500-100.asp" by default. This is the default error-handling page on your system, which normally handles ASP errors if you do not define a custom handler. Note that you can open this page in a text editor to examine its error-handling techniques.
  7. To enable your custom handler, type the virtual path to your ASP page. For example, if your ErrTest virtual directory is immediately beneath the root Web site on your server, type the following path:

    /ErrTest/My500ErrHandler.asp

  8. Click OK twice to close the dialog boxes and set your custom error-handler.
back to the top

Test Your Custom Error Handler

Test One: Run-Time Error

The following page illustrates a run-time error, which you receive when you perform an operation that is impossible to complete, such as division by zero:
  1. Click Start, point to Programs, point to Accessories, and then click Notepad.
  2. Paste the following code:
    <%@Language="VBSCRIPT"%>
<html>
<head>
<title>Bad Page 1</title>
</head>
<body>
<% Response.Write 1/0 %>
</body>
</html>
  3. On the File menu, click Save. When you are prompted, name the page BadPage1.asp, and save the page to the ErrTest folder that you created earlier.
  4. In your Web browser, type the following URL in the Address bar to browse to the page:

    http://<Your_Server_Name>/ErrTest/BadPage1.asp

back to the top

Test Two: Invalid Method in Code

The following page illustrates what happens if the code calls a method that does not exist or is misspelled in the reference to one of the intrinsic ASP objects:
  1. From the Start menu, point to Programs, point to Accessories, and then click Notepad.
  2. Paste the following code:
    <%@Language="VBSCRIPT"%>
<html>
<head>
<title>Bad Page 2</title>
</head>
<body>
<% Response.BadMethod "Hello" %>
</body>
</html>
  3. From the File menu, click Save. When you are prompted, name the page BadPage2.asp, and save the page to the ErrTest folder that you created earlier.
  4. In your Web browser, type the following URL in the Address bar to browse to the page:

    http://<Your_Server_Name>/ErrTest/BadPage2.asp

back to the top

Test Three: Unregistered Object

The following page illustrates the error that you receive when you try to create an external object that is not registered on the server:
  1. From the Start menu, point to Programs, point to Accessories, and then click Notepad.
  2. Paste the following code:
    <%@Language="VBSCRIPT"%>
<html>
<head>
<title>Bad Page 3</title>
</head>
<body>
<%
 Dim objBad
 Set objBad = Server.CreateObject("BAD.OBJECT.CLASS")
%>
</body>
</html>
  3. From the File menu, click Save. When you are prompted, name the page BadPage3.asp, and save the page to the ErrTest folder that you created earlier.
  4. In your Web browser, type the following URL in the Address bar to browse to the page:

    http://<Your_Server_Name>/ErrTest/BadPage3.asp

back to the top

Troubleshooting

  • When you are building a custom error handler, you should be aware of two additional ASP concepts: the Server.Transfer method and the Server.GetLastError method. The Server.Transfer method transfers execution to the error-handling page that is defined in your application. Because Server.Transfer occurs automatically, normally you do not have to deal with it. The Server.GetLastError method is used to return the ASPError object in your error-handling page. You do not have to use this method, and it is included in the preceding sample error-handling page. For more information about both methods, see the "References" section.
  • The built-in error handler can handle errors regardless of whether the page that causes the error is written in JScript or VBScript; however, the basic sample in this article only returns meaningful information about errors that come from VBScript pages. If your page is written in JScript, you may need to build an error handler that is specific to JScript; or, if you need your error handler to manage errors from any type of page, study the default error-handling page to see the techniques that are used.
  • Microsoft Internet Explorer 5 or later includes a setting that may override standard HTTP Web server error messages, which can lead to unexpected behavior in your browser. To turn off this feature, on the Tools menu in your browser, click Internet Options. On the Advanced tab, clear the Show Friendly HTTP Error Messages check box.
  • Also remember that you can still use inline error handling, and inline error handling overrides the centralized error handler. To demonstrate this, open BadPage1.asp in Notepad, and paste the following modified code, which adds an inline error handler: 
    <%@Language="VBSCRIPT"%>
<html>
<head>
<title>Bad Page 1</title>
</head>
<body>
<% 

On error resume next

Response.Write 1/0 

if err.number <> 0 then
    Response.Write err.description & "<BR>" & err.source & "<BR>"
    err.clear
end if

%>
</body>
</html>
    Save these changes, and browse to the file in your Web browser. Notice that your inline error handler overrides the centralized error handler that you created.
back to the top

REFERENCES

Microsoft Knowledge Base Articles

224070 Creating Custom ASP Error Pages

219294 How to Use the Server.Transfer Method

294271 INFO: ASP Error Codes

back to the top

MSDN Documentation

Using the New Features in Internet Information Server 5.0: Part 2
http://msdn.microsoft.com/library/periodic/period01/asp0132.htm

ASPError Object
http://msdn.microsoft.com/library/default.asp?url=/library/en-us/iissdk/html/541697df-5fb9-40a4-8fa1-380b4717cbf1.asp

GetLastError
http://msdn.microsoft.com/library/default.asp?url=/library/en-us/debug/base/getlasterror.asp

NOTE: The MSDN documentation that is listed above is also included with IIS 5.0 and is installed on your system (typically in the http://localhost/iishelp folder).

back to the top

Third-Party Content

Error Reporting - IIS 5.0
http://www.15seconds.com/Issue/010418.htm

back to the top















Modification Type:MajorLast Reviewed:1/18/2006
Keywords:kbBug kbCodeSnippet kbConfig kbDebug kbGuidelines kbHOWTOmaster kbSample kbScript kbWebServer KB299981 kbAudDeveloper
©2004 Microsoft Corporation. All rights reserved.