Lesson 1: Using Exception Handling

Lesson 1: Using Exception Handling

Exceptions are unusual occurrences that happen within the logic of an application. The terms exception and error are often used interchangeably in the Visual Studio .NET documentation because you use the same programming techniques to handle either situation.

In this lesson, you ll learn the different programming techniques that you can use to handle exceptions in a Web application. This lesson discusses only the modern techniques provided by Visual Studio .NET and Microsoft ASP.NET. It does not cover earlier exception-handling syntax, such as On Error, which is still supported by Visual Basic .NET.

After this lesson, you will be able to

• Explain the two main exception-handling techniques used in Web applications

• Create an exception-handling structure to catch and handle exceptions within a procedure

• Cause exceptions to occur in response to unexpected occurrences

• Define new exceptions that your application can use to describe exception conditions

• Handle exceptions from within error events

Estimated lesson time: 30 minutes

Exception-Handling Techniques

When an unanticipated problem occurs in a Web application, it is immediately apparent to the user. Figure 6-1 shows what the user sees if a Web application tries to open a file that doesn t exist on the server.

Figure 6-1. An unhandled exception

When this happens, the user is stuck he or she can only click Back on the browser and try again. As a programmer, you are responsible for anticipating and dealing with these situations in your code before they occur. The process of dealing with these types of situations is called exception handling. Errors that are not dealt with in code are called unhandled exceptions, and they appear to the user as shown in Figure 6-1.

There are three approaches to handling exceptions in a Web application:

• Use exception-handling structures to deal with exceptions within the scope of a procedure. This technique is called structured exception handling (SEH) in the Visual Studio .NET documentation.

• Use error events to deal with exceptions within the scope of an object.

• Use custom error pages to display informational messages for unhandled exceptions within the scope of a Web application.

You can combine approaches to effectively handle all possible exceptions within your application, as explained in the following sections.

Using Exception-Handling Structures

Use exception-handling structures to enclose statements that access nonmemory resources, such as files and database connections. Access to these types of resources might fail because of external conditions. A common situation where you need exception handling is accessing files. When you try to read a file from disk, a variety of problems can occur: the file might not be found, the file might be locked because it is already open, or access might be denied because of security settings.

To deal with these potential problems, enclose the file access statements in an exception-handling structure. Table 6-1 describes the keywords used to create an exception-handling block.

Table 6-1. Exception-Handling Keywords

Visual Basic .NET keyword	Visual C# keyword	Use to
Try	try	Begin an error-handling structure. If a statement that follows this keyword causes an exception, control flow passes immediately to the next Catch/catch statement.
Catch	catch	Retrieve any exceptions that occurred and handle them. When control flow passes to a Catch/catch block, the statements contained in the block are processed to correct the error or otherwise handle the exception.
Finally	finally	Free resources used within the Try/try section and process any other statements that must run, whether or not an exception has occurred.
End Try	N/A	End an exception-handling structure.
Throw	throw	Cause an exception to occur. Use this keyword within your exception-handling structure to immediately pass control flow to the Catch/catch statement.

The easiest way to demonstrate how to use these keywords together is with an example. Figure 6-2 shows a Web form that allows the user to select a file from his or her machine to upload to the server. When the file is uploaded, it is added to the list box.

Figure 6-2. File upload sample

When the user enters a file name on the Web form and clicks Upload, a number of exception conditions can occur:

• The file might not exist on the client s computer.

• The file might already exist on the server.

• The file might be too large to transfer over the Internet.

• The server might not have enough available disk space for the file.

To handle these and other unforeseen conditions, enclose the statements that might cause these conditions in an exception-handling structure, as shown in the following code:

Visual Basic .NET

Dim strPath As String = Server.MapPath("./uploadfiles/") Private Sub butUpload_Click(ByVal sender As System.Object, _ ByVal e As System.EventArgs) Handles butUpload.Click Dim strFilename As String = filUpload.PostedFile.FileName ' Get the file name from the uploaded file spec. strFilename = Path.GetFileName(strFilename) Try ' (1) Check if file is zero-length (file does not exist). If filUpload.PostedFile.ContentLength = 0 Then _ Throw New FileNotFoundException ' (2) Save uploaded file to server using the file base name. filUpload.PostedFile.SaveAs(strPath + strFilename) ' Set the file a ReadOnly so it can't be overwritten. File.SetAttributes(strPath + strFilename, FileAttributes.ReadOnly) ' Add file to list of server files. lstFiles.Items.Add(strFilename) ' Display success if no errors. litError.Text = strFilename + " uploaded successfully." ' (3) Handle possible exceptions. Catch ex As System.IO.FileNotFoundException litError.Text = "The file does not exist or is zero-length." Catch ex As System.UnauthorizedAccessException litError.Text = "You must delete the file from the server " + _  "before uploading a new version." ' Enable the delete button butDelete.Visible = True ' Select the existing file in the list box. lstFiles.Items.FindByText(strFilename).Selected = True Catch ex As Exception litError.Text = "The following error occurred:<br>" litError.Text += ex.Message End Try End Sub

Visual C#

private void butUpload_Click(object sender, System.EventArgs e) { strPath=Server.MapPath("./uploadfiles/"); // Hide delete button if it was displayed. butDelete.Visible = false; // Get the uploaded file spec. string strFilename = filUpload.PostedFile.FileName; // Get the filename from the file spec. strFilename = Path.GetFileName(strFilename); try { // (1) Check if file is zero-length (file does not exist). if (filUpload.PostedFile.ContentLength == 0) throw new System.IO.FileNotFoundException(); // (2) Save uploaded file to server using the file base name. filUpload.PostedFile.SaveAs(strPath + "\\" + strFilename); // Set the file a ReadOnly so it can't be overwritten. File.SetAttributes(strPath + strFilename, FileAttributes.ReadOnly); // Add file to list of server files. lstFiles.Items.Add(strFilename); // Select the first item in the list box. lstFiles.SelectedIndex = 0; // Display success if no errors. litError.Text = strFilename + " uploaded successfully."; } // (3) Handle possible exceptions. catch (System.IO.FileNotFoundException) { litError.Text = "The file does not exist."; } catch ( System.UnauthorizedAccessException) { litError.Text = "You must delete the file from the server "; litError.Text += "before uploading a new version."; // Enable the delete button. butDelete.Visible = true; // Select the existing file in the list box. lstFiles.Items.FindByText(strFilename).Selected = true; } catch (Exception ex) { litError.Text = "The following error occurred:<br>"; litError.Text += ex.Message; } }

As the preceding code executes, it follows these steps:

1. Checks whether the file exists on the client machine. If the entered file has zero length, the file does not exist, so the code throws the System.IO.FileNotFound Exception, and control flow passes immediately to step 3.

2. Saves the file to the server. If saving succeeds, control flow continues by adding the file name to the ListBox control and displaying success. If saving fails, control flow passes to step 3.

3. Handles exceptions. In this case, exceptions are handled by displaying a message on the Web form. If no exceptions occurred, control flow skips to the end of the exception-handling structure. Catch blocks are evaluated in the order in which they appear in code. The exception declaration of each catch block determines which type of exception the catch block handles. Always order catch blocks from most specific to most general. So, in the preceding sample, FileNotFoundException and UnAuthorizedAccessException catch blocks are placed before the general Exception catch block.

Use the Finally/finally block to include statements that are always executed before leaving the exception-handling structure. For example, in the following code, the Return/return statement in the catch block causes execution to skip the rest of the procedure when an exception occurs; however, the finally block is always executed whether or not an exception occurred.

Visual Basic .NET

 Private Sub butDelete_Click(ByVal sender As System.Object, _ ByVal e As System.EventArgs) Handles butDelete.Click Try ' Set the file attributes to allow deletion. File.SetAttributes(strPath + lstFiles.SelectedItem.Text, _ FileAttributes.Normal) ' Delete the file. File.Delete(strPath + lstFiles.SelectedItem.Text) ' Remove the file from the list. lstFiles.Items.Remove(lstFiles.SelectedItem) Catch ex As Exception litError.Text = "Could not delete the file due to this error: " litError.Text += ex.Message Return Finally ' Hide this button. butDelete.Visible = False End Try ' Show success. litError.Text = "File deleted." End Sub

Visual C#

private void butDelete_Click(object sender, System.EventArgs e) { try { // Set the file attributes to allow deletion. File.SetAttributes(strPath + lstFiles.SelectedItem.Text, FileAttributes.Normal); // Delete the file. File.Delete(strPath + lstFiles.SelectedItem.Text); // Remove the file from the list. lstFiles.Items.Remove(lstFiles.SelectedItem); } catch (Exception ex ) { litError.Text = "Could not delete the file due to this error: "; litError.Text += ex.Message; return; } finally { // Hide this button. butDelete.Visible = false; } // Show success. litError.Text = "File deleted."; }

The Microsoft .NET Framework includes specific exception types with the individual .NET Framework classes. This means that there is no single, comprehensive list of exception types in the .NET documentation. Instead, you must use the Visual Studio .NET Exceptions dialog box to view specific exception types, as described in the following procedure.

To view the exception types that the .NET Framework provides, follow these steps:

1. From the Debug menu, choose Exceptions. Visual Studio .NET displays the Exceptions dialog box, as shown in Figure 6-3.

   

   Figure 6-3. The Exceptions dialog box

2. Click the plus signs to the left of items in the Exceptions list to see the exceptions each item provides.

Causing Exceptions

As you saw in the preceding section, you use the Throw/throw keyword to cause specific exceptions to occur. This technique is useful to illustrate how exception handling works, but it begs the question, Why would you want to cause an exception in a real-world application?

Exception handling is a way to implement a certain kind of logic in your application. You are simply specifying a set of occurrences that are not normally part of the application s course of events and then saying, These are the exceptions. That lets you set aside the complexity of dealing with those exceptions, thereby simplifying the main logic of your application.

For example, in the preceding File Upload sample, it s reasonable to cause the FileNotFoundException exception if the uploaded file has a length of 0. Otherwise, it s very difficult to determine whether a file exists on a client s machine before uploading. FileNotFoundException is a standard exception in the System.IO namespace, and it is descriptive of what happened.

Defining New Exceptions

In some cases, you ll want to cause an exception in your application that doesn t have an effective, descriptive equivalent in the .NET Framework. In those cases, you should create a new exception of the type ApplicationException. For example, the following code fragment causes an exception indicating that the user is already logged on:

Visual Basic .NET

Throw New ApplicationException("User is already logged on.")

Visual C#

throw new ApplicationException("User is already logged on.");

To handle this exception, use the following Catch/catch statement:

Visual Basic .NET

Catch ex As ApplicationException

Visual C#

catch (ApplicationException ex)

The ApplicationException class provides the same features as the standard Exception class. It simply provides a way to differentiate between those exceptions defined in the .NET Framework and those defined in your application.

If you are creating a large application or creating components that are used by other applications, you might want to define your own exception classes based on the ApplicationException class. For example, the following code defines a class for the UserLoggedOnException:

Visual Basic .NET

Public Class UserLoggedOnException Inherits ApplicationException ' Exception constructor. Sub New(Optional ByVal Message As String = "The user is already " & _  "logged on to the server.", _ Optional ByVal Inner As Exception = Nothing) MyBase.New(Message, Inner) End Sub End Class

Visual C#

public class UserLoggedOnException : System.ApplicationException { // Exception constructor (overloaded). public UserLoggedOnException() : this("The user is already logged on to the server", null) { } public UserLoggedOnException(string message) : this(message, null) { } public UserLoggedOnException(string message, Exception inner) : base(message, inner) { } }

The preceding UserLoggedOnException class inherits its properties and methods from the ApplicationException base class. The new exception class provides only its own constructor to set the default message to display. This is a standard practice.

Using Error Events

Another way to handle exceptions is through the Web objects built-in error events. When an unhandled exception occurs in a Web application, ASP.NET fires the error events described in Table 6-2.

Table 6-2. Exception-Handling Events

Event procedure	Occurs when
Page_Error	An unhandled exception occurs on the page. This event procedure resides in the Web form.
Global_Error	An unhandled exception occurs in the application. This event procedure resides in the Global.asax file.
Application_Error	An unhandled exception occurs in the application. This event procedure resides in the Global.asax file.

Error events let you handle exceptions for an entire object in a single, centralized location the error event procedure. This is different from using exception-handling structures, in which exceptions are handled within the procedure where they occurred. You can use error events in the following ways:

• As a substitute for exception-handling structures

  Because error events occur outside the scope of the procedure in which the error occurred, you have less information about the steps leading up to the exception and therefore less ability to correct the exception condition for the user. However, using exception-handling events is fine for tasks where you might not be able to correct the exception in code.

• As an adjunct to exception-handling structures.

  Error events can provide a centralized backstop against exceptions that were not foreseen or handled elsewhere. Using the two exception-handling techniques together lets you catch all exceptions before the user sees them, display a reasonable message, and even record the exception in a log as part of an ongoing effort to improve your application.

When handling exceptions in error events, use the Server object to get information about the exception that occurred. The Server object provides the methods described in Table 6-3 for working with exceptions.

Table 6-3. The Server Object s Exception-Handling Events

Server method	Use to
GetLastError	Get the last exception that occurred on the server.
ClearError	Clear the last exception that occurred on the server. Invoking Clear Error handles the exception so that it doesn t trigger subsequent error events or appear to the user in the browser.

To handle an exception in an error event, follow these steps:

1. In the Page_Error, Global_Error, or Application_Error event procedure, get the exception that occurred using the GetLastError method.

2. Do something with the exception, such as display a message to the user, take steps to correct the problem, or write to an error log.

3. Clear the exception using the ClearError method.

4. Redisplay the page. Web form processing stops immediately when an exception occurs, so server controls and other items on the page might not be displayed after the exception is cleared.

The following code demonstrates these steps:

Visual Basic .NET

Private Sub Page_Error(ByVal sender As Object, _ ByVal e As System.EventArgs) Handles MyBase.Error ' Get error. Dim ex As Exception = Server.GetLastError() ' Store the error message. Session("Error") = ex.Message() ' Clear error. Server.ClearError() ' Transfer back to this page. Server.Transfer ("ErrorEvents.aspx") End Sub

Visual C#

private void Page_Error(object sender, System.EventArgs e) { // Get the error. Exception ex = Server.GetLastError(); // Store the message. Session["Error"] = ex.Message; // Clear the error. Server.ClearError(); // Redisplay this page. Server.Transfer("ErrorEvents.aspx"); }

The preceding code stores the exception message as a Session state variable before clearing the exception so that the message can be displayed when the page is reloaded by the Transfer method. The following code displays the saved exception message when the page is redisplayed:

Visual Basic .NET

Private Sub Page_Load(ByVal sender As System.Object, _ ByVal e As System.EventArgs) Handles MyBase.Load ' Display error. if any. If Session("Error") <> Nothing Then litError.Text = "The following error occurred:<br>" + _ Session("Error") ' Clear the Session state variable. Session("Error") = Nothing End If End Sub

Visual C#

private void Page_Load(object sender, System.EventArgs e) { // Display error. if any. if(Session["Error"] != null) { litError.Text = "The following error occurred:<br>" + Session["Error"].ToString(); // Clear the Session state variable. Session["Error"] = null; } }