Lab 7: Logging and Exception Handling

Purpose

Estimated time to complete this lab: 20 minutes

Solutions created with the Web Client Solution template provide out-of-the-box exception logging and shielding. The solutions use Enterprise Library and ASP.NET configuration to prevent transmission of sensitive information to end users in the event of a run-time exception and for simplified management and diagnostics.

Exception logging and shielding is implemented with an HTTP module in the Composite Web Application Block. This module uses the Enterprise Library Exception Handling Application Block and the Logging Application Block. The bold lines of the following code extracted from the root Web.config file of the Web site shows how the HTTP module is registered in the ASP.NET pipeline.

<httpModules>

      <add name="WebClientAuthorizationModule" type="Microsoft.Practices.CompositeWeb.Authorization.WebClientAuthorizationModule, Microsoft.Practices.CompositeWeb" />

      <add name="ExceptionLoggerHttpModule" type="Microsoft.Practices.CompositeWeb.EnterpriseLibrary.ExceptionLogger, Microsoft.Practices.CompositeWeb.EnterpriseLibrary" />

</httpModules>

Note: For more information about HTTP modules, see Introduction to HTTP Modules.

The ExceptionLogger class catches all unhandled exceptions and uses the Exception Handling Application Block to handle them. The Web.config file of the Web Client Solution template defines the configuration for the Exception Handling Application Block, and the default configuration defines that exceptions are logged to the Windows Event Log.

You can manually edit the Web.config file or use Enterprise Library Configuration Editor to change the exception handling policy and logging behavior. In this exercise, you learn how Web client solutions handle exceptions and how you can change the configuration to customize the exception handling and logging behavior of your Web client application.

Preparation

Before proceeding with this lab, you must install and configure the prerequisite software. For more information, see Web Client Software Factory Hands-On Labs.

Open the solution for the previous lab (either the one that you created or the end solution for that lab.) If you use the provided end solution, you must enable the guidance package for that solution.

To enable the Web Client Development guidance package with the Guidance Package Manager

1.       Using Visual Studio, open the solution.

2.       On the Tools menu, click Guidance Package Manager.

3.       In the Guidance Package Manager dialog box, click Enable / Disable Packages.

4.       In the Enable and Disable Packages dialog box, select the Web Client Development check box.

5.       Click OK.

Procedures

This lab includes the following tasks:

·         Task 1: Update the Admin Module’s Default Page to Throw an Exception

·         Task 2: Create a Custom Error Page and Configure the Application to Use It

·         Task 3: Run and Examine the Error Information

·         Task 4: Update the Logging Application Block Configuration

·         Task 5: Update the Exception Handling Application Block Configuration

·         Task 6: Add a Button to the Admin Module’s Default Page to Throw a NotImplementedException

The next sections describe each of these tasks.

Task 1: Update the Admin Module’s Default Page to Throw an Exception

In this task, you will add a button to the default page of the Admin module; this button throws an exception when it is clicked. You will use this button to simulate an application exception and observe the application behavior.

To update the Admin module’s default page to throw an exception

1.       Add a button to the Default.aspx page of the Admin module. To do this in Solution Explorer, double-click the page Admin/Default.aspx located in the DevelopmentWebsite site, and then drag a Button control from the Toolbox onto the page.

2.       Change the ID property of the button to ThrowApplicationExceptionButton, and then change the Text property to Throw ApplicationException.

3.       Double-click the button to add an event handler for the click event, and then add the bold line in the following code to the event handler. This code throws an exception of type ApplicationException.

protected void ThrowApplicationExceptionButton_Click(object sender, EventArgs e)

{

    throw new ApplicationException("ApplicationException test");

}

Task 2: Create a Custom Error Page and Configure the Application to Use It

Using ASP.NET, you can specify custom error pages that are displayed to the user when run-time errors occur. When you create a solution using the Web Client Solution template, the application configuration file specifies that errors with code 403 (“Access Forbidden”) are to redirect the user to a custom error page (DevelopmentWebsite/Errors/AccessDenied.htm). In this task, you will create a custom error page for errors with code 500 (“Internal Server Error”) and configure the Web site to display that page when errors with that code occur.

Note: Unhandled exceptions of type ApplicationException will produce an HTTP error with the code 500 (“Internal Server Error”). This means that you can click the ThrowApplicationExceptionButton button that you added in the previous task to generate an error 500.

To create a custom error page and configure the application to use it

1.       Create a new HTML page in the Errors folder of the DevelopmentWebsite site. To do this, right-click the Errors folder, and then click Add New Item. Under Templates in the Add New Item dialog box, click HTML Page, type ApplicationError.htm in the Name box, and then click Add.

2.       Open the Source view for the page, and then replace the contents with the following markup.

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" >

<head>

    <title>Application Error</title>

</head>

<body>

    <p>An error has occurred in the application.</p>

</body>

</html>

3.       Open the Web.config file located in the root of DevelopmentWebsite and add the bold line in the following XML to the customErrors element. This line specifies that for the error 500 (“Internal Server Error”), ASP.NET will redirect the application to the URL ~/Errors/ApplicationError.htm.

<customErrors mode="On">

  <error statusCode="403" redirect="~/Errors/AccessDenied.htm" />

  <error statusCode="500" redirect="~/Errors/ApplicationError.htm" />

</customErrors>

Note: For more information about the customErrors element, see customErrors Element (ASP.NET Settings Schema).

Task 3: Run and Examine the Error Information

In this task, you will run the Web site and generate an exception of type ApplicationException to observe the application behavior.

To run and examine the error information

1.       In Visual Studio, press CTRL+F5 to run the application without the debugger attached.

Note: If you run the application with the debugger attached, exceptions will be handled by the debugger, and you will not see the intended behavior.

2.       Click the Admin button in the site map to navigate to the default page of the Admin module.

3.       Click the ThrowApplicationExceptionButton button to throw an exception of type ApplicationException.

4.       Open the Application event log in the Event Viewer. To do this, perform the following steps:

a. On the Windows taskbar, click Start, and then click Run. (Alternatively, press the Windows logo key + R.)

b.      In the Open box, type eventvwr.msc, and then click OK. This opens the Event Viewer.

c. Locate the Application node in the tree on the left.

Note: If you are using Windows Vista, this node should be under Windows Logs.

5.       Examine the last entry from the source “Enterprise Library Logging.” This is the entry that is added by the logging exception handler used in your Web client application.

Task 4: Update the Logging Application Block Configuration

In this task, you will configure the Logging Application Block to log all exceptions of type NotImplementedException to a text file.

To update the Logging Application Block configuration

1.       In Solution Explorer, right-click the Web.config file in the root of the Web site, and then click Edit Enterprise Library Configuration. This opens the Enterprise Library Configuration Editor. The Configuration Editor is used to create and modify configuration files. It has the same functionality as the stand-alone Enterprise Library Configuration Console, but it uses the Visual Studio Properties window to display application block properties and uses the errors list to display configuration errors.

Note: You must download and install Enterprise Library to see this option. If you do not see this option, you can use the Enterprise Library Configuration Console to edit the configuration file. (The Web Client Software Factory includes the Enterprise Library Configuration Console.)

2.       Expand the Logging Application Block node. Trace listeners receive log entries and write them to the configured destinations. In the next step, you will add a trace listener that writes log entries to a flat file.

3.       Right-click the Trace Listeners node, point to New, and then click Flat File Trace Listener. You can use category sources to assign log entries to categories. In the next step, you will add a new category source for exceptions of type NotImplementedException. By doing this, you will be able to perform specific actions for this type of exceptions.

4.       Right-click the Category Sources node, point to New, and then click Category. Using the Properties window, change the Name property of the category to NotImplementedException.

To route the log entries for a particular category to a trace listener, you define trace listener references inside a category node. In the following steps, you will add two trace listener references for the NotImplementedException category, one for the Flat File Trace Listener and one for the Formatted EventLog Trace Listener. These trace listeners write entries to a flat file and to the event log, respectively.

5.       Under Category Sources, right-click the NotImplementedException node, point to New, and then click Trace Listener Reference. In the Properties window, select FlatFile TraceListener in the ReferencedTraceListener drop-down list box.

6.       Under Category Sources, right-click the NotImplementedException node, point to New, and then click Trace Listener Reference. In the Properties window, select Formatted EventLog TraceListener in the ReferencedTraceListener drop-down list box.

Task 5: Update the Exception Handling Application Block Configuration

In this task, you will configure the Exception Handling Application Block to route all the exceptions of type NotImplementedException to a logging handler specifying the NotImplementedException category source, so they get logged in both a flat file and in the event log.

To update the Exception Handling Application Block configuration

1.       Under the Exception Handling Application Block node, right-click GlobalExceptionLogger, point to New, and then click Exception Type.

2.       Under the System namespace, click NotImplementedException.

3.       Under GlobalExceptionLogger, right-click NotImplementedException, point to New, and then click Logging Handler.

4.       Set TextExceptionFormatter as the FormatterType.

5.       Set NotImplementedException as the LogCategory.

6.       Save the file.

Task 6: Add a Button to the Admin Module’s Default Page to Throw a NotImplementedException

In this task, you will add a new button to the Admin module’s default page to throw a NotImplementedException exception. You will use the button to test the new logging and exception handling configuration.

To add a button to the Admin module’s default page to throw a NotImplementedException

1.       Drag a Button control from the Toolbox onto the Default.aspx page of the Admin module.

2.       Change the ID property of the button to ThrowNotImplementedExceptionButton, and then change the Text property to Throw NotImplementedException.

3.       Double-click the button to add an event handler for the click event, and then add the following code to throw an exception of type NotImplementedException.

protected void ThrowNotImplementedExceptionButton_Click(object sender, EventArgs e)

{

    throw new NotImplementedException("Feature under development.");

}

Verification

In this section, you will run the Web site and generate an exception of type NotImplementedException to observe the application behavior.

To run the Web site and generate an exception of type NotImplementedException

1.       In Visual Studio, press CTRL+F5 to run the application without the debugger attached.

2.       Click the Admin button in the site map to navigate to the default page of the Admin module.

3.       Click the ThrowNotImplementedExceptionButton button to throw an exception of type NotImplementedException.

4.       Open the application event log in the Event Viewer, as you did in Task 3, and then examine the entry from the source Enterprise Library Logging.

5.       Open the file trace.log in the root folder of the DevelopmentWebsite site. The file should have an entry for the NotImplementedException exception.