Lesson 2: Using Error Pages

Lesson 2: Using Error Pages

Lesson 1 provided techniques for handling exceptions that occur on the server running your Web application. However, because Web applications run over the Internet, there s a whole class of exceptions that can t be detected from within code. To intercept these errors and provide the best possible response, you need to use error pages.

In this lesson, you ll learn how to use error pages in ASP.NET to intercept and respond to HTTP errors at the application and page levels.

After this lesson, you will be able to

• Identify types of exceptions that can t be detected from within application code

• Respond to HTTP exceptions at the application and page levels

• Specify error pages for specific HTTP errors using the Web.config file

Estimated lesson time: 15 minutes

Handling Internet-Related Exceptions

When a user runs a Web application from his or her browser, a variety of exceptions can occur outside the scope of the actual application. For example, server errors can occur when a server times out waiting for a response from a user or when the page requested by a user isn t found on the server.

When these types of events happen, ASP.NET displays an error page like the one shown in Figure 6-4.

Figure 6-4. Page not found error page

Error pages are .htm or .aspx pages on the server that the user is redirected to if an unhandled exception occurs. ASP.NET lets you define error pages at two levels:

• Specify application-wide error page settings in the customErrors section of the Web.config file.

  These settings determine the page to display for specific HTTP errors.

• Specify an error page for a specific Web form in the ErrorPage attribute of the Web form s @ Page directive.

  This setting determines the error page to display if the Web form encounters an unhandled exception.

The following sections describe these levels in more detail.

Using Application-Wide Error Pages

Microsoft Internet Information Services (IIS) defines the error pages that are displayed by default for specific HTTP responses. To see or change the error page settings for an application in IIS, follow these steps:

1. Right-click the Web application folder, and select Properties from the shortcut menu. IIS displays the application s Properties dialog box.

2. Click the Custom Errors tab in the Properties dialog box. IIS displays the error page settings for specific HTTP response codes, as shown in Figure 6-5.

   

   Figure 6-5. IIS Custom Errors settings

3. Select the response code you want to change the error page for in the Error Messages For HTTP Errors list, and then click Edit Properties to change the setting. IIS displays the Error Mapping Properties dialog box, as shown in Figure 6-6.

   

   Figure 6-6. IIS Error Mapping Properties dialog box

4. Click Browse to replace the default error page with a page from your own application folder. Click OK in each dialog box when you have finished.

Using IIS to change application-wide error pages makes the changes on the server where the application is deployed. If you redeploy your application, you will have to repeat those changes for the new server using IIS. Alternatively, you can make application-wide error page settings part of your application using the project s Web.config file.

Use the customErrors section in the Web.config file to specify pages to display if specific, unhandled HTTP errors occur in a Web application. HTTP errors are identified by status codes defined in the HTTP 1.1 specification. ASP.NET lists these status codes in the HTTPStatusCode enumeration. Some of the common status codes are listed in Table 6-4.

Table 6-4. Common HTTP Status Codes

Status code value	HTTPStatusCode member	Indicates
200	OK	The request succeeded.
204	NoContent	The request succeeded, but the response is intentionally blank.
301	Moved, MovedPermanently	The request is being redirected to another address.
302	Found, Redirect	The request is being redirected to another address.
400	BadRequest	The request could not be understood by the server.
401	Unauthorized	The requested resource requires authorization, which was not provided with the request.
403	Forbidden	The server refuses to fulfill the request.
404	NotFound	The requested resource does not exist on the server.
408	RequestTimeOut	The client did not send a request before the server s request time-out occurred.
500	InternalServerError	A generic error occurred on the server. This error code represents any unhandled exception that occurs within the application.
503	ServiceUnavailable	The server is temporarily unavailable.
505	HttpVersionNotSupported	The requested HTTP version is not supported by the server.

To display a specific page in response to one or more of these status codes, include an <error> tag in the customErrors section of your application s Web.config file. For example, the following customErrors section specifies a default error page to display, along with three different error pages for specific HTTP response codes that indicate errors:

<customErrors mode="On" defaultRedirect="ErrDefault.aspx"> <error statusCode="401" redirect="ErrUnauthorized.aspx" /> <error statusCode="404" redirect="ErrPageNotFound.aspx" /> <error statusCode="500" redirect="ErrServer.htm" /> </customErrors>

The customErrors mode attribute must equal On to view the error pages while debugging the application on your local machine. Setting the mode to RemoteOnly (the default) will display the designated error pages when the application is accessed from client computers, but not when the application is accessed locally.

The customErrors settings in Web.config apply only to resource types that ASP.NET considers to be part of the Web application. For example, the custom error page for Page Not Found (status code 404) will not be displayed when redirecting to a page with the .htm or .html file type. To intercept those cases, use the IIS settings.

NOTE
The HTTP status code 500 represents an unhandled exception in the Web application. This status code can be used to present a friendly message to users or to automatically notify the development team when users are encountering unhandled exceptions.

Using Page-Level Error Pages

Use the Page object s ErrorPage attribute to display a specific page when an unhandled exception occurs on a Web form. The page-level setting supersedes the application-level settings in the Web.config file.

For example, the following HTML sets the ErrorPage attribute for a Web form:

Visual Basic .NET

<%@ Page Language="vb" AutoEventWireup="false"  Codebehind="ErrorPages.aspx.vb"  Inherits="MCSDWebAppsVB.ErrorPages" errorPage="ErrDefault.aspx"%>

Visual C#

<%@ Page language="c#" Codebehind="ErrorPages.aspx.cs"  AutoEventWireup="false" Inherits="MCSDWebAppsCS.ErrorPages"  errorPage="ErrDefault.aspx"%>

The following code then causes an exception when the user clicks butError:

Visual Basic .NET

Private Sub butError_Click(ByVal sender As System.Object, _ ByVal e As System.EventArgs) Handles butError.Click ' Cause exception. Throw New System.Net.WebException() End Sub

Visual C#

private void butError_Click(object sender, System.EventArgs e) { // Cause exception. throw new System.Net.WebException(); }

When the exception occurs, the user is redirected to the ErrDefault.aspx page. Because ErrDefault.aspx is displayed through redirection, the context for the error is lost and Server.GetLastError returns nothing from the target error page.