Pro CSharp 2008 And The .NET 3.5 Platform [eng]-1

222 CHAPTER 7 ■ UNDERSTANDING STRUCTURED EXCEPTION HANDLING

As you can see, many of the properties defined by System.Exception are read-only in nature. This is due to the simple fact that derived types will typically supply default values for each property (for example, the default message of the IndexOutOfRangeException type is “Index was outside the bounds of the array”).

■Note The Exception class implements two .NET interfaces. Although we have yet to examine interfaces

(see Chapter 9), simply understand that the _Exception interface allows a .NET exception to be processed by an unmanaged code base (such as a COM application), while the ISerializable interface allows an exception object to be persisted across boundaries (such as a machine boundary).

Table 7-1 describes the details of some (but not all) of the members of System.Exception.

Table 7-1. Core Members of the System.Exception Type

The Simplest Possible Example

To illustrate the usefulness of structured exception handling, we need to create a type that may throw an exception under the correct circumstances. Assume we have created a new C# Console Application project (named SimpleException) that defines two class types (Car and Radio) associated by the “has-a” relationship. The Radio type defines a single method that turns the radio’s power on or off:

class Radio

{

public void TurnOn(bool on)

{

if(on) Console.WriteLine("Jamming...");

else

Console.WriteLine("Quiet time...");

}

}

In addition to leveraging the Radio type via containment/delegation, the Car type is defined in such a way that if the user accelerates a Car object beyond a predefined maximum speed (specified using a constant member variable named MaxSpeed), its engine explodes, rendering the Car unusable (captured by a bool member variable named carIsDead).

Beyond these points, the Car type has a few member variables to represent the current speed and a user supplied “pet name” as well as various constructors to set the state of a new Car object. Here is the complete definition (with code annotations):

class Car

{

//Constant for maximum speed. public const int MaxSpeed = 100;

//Internal state data.

private int currSpeed; private string petName;

//Is the car still operational? private bool carIsDead;

//A car has-a radio.

private Radio theMusicBox = new Radio();

// Constructors. public Car() {}

public Car(string name, int currSp)

{

currSpeed = currSp; petName = name;

}

public void CrankTunes(bool state)

{

// Delegate request to inner object. theMusicBox.TurnOn(state);

}

// See if Car has overheated. public void Accelerate(int delta)

{

if (carIsDead)

Console.WriteLine("{0} is out of order...", petName); else

{

currSpeed += delta;

if (currSpeed > MaxSpeed)

{

Console.WriteLine("{0} has overheated!", petName); currSpeed = 0;

224 CHAPTER 7 ■ UNDERSTANDING STRUCTURED EXCEPTION HANDLING

carIsDead = true;

}

else

Console.WriteLine("=> CurrSpeed = {0}", currSpeed);

}

}

}

Now, if we were to implement a Main() method that forces a Car object to exceed the predefined maximum speed as shown here:

static void Main(string[] args)

{

Console.WriteLine("***** Simple Exception Example *****");

Console.WriteLine("=> Creating a car and stepping on it!"); Car myCar = new Car("Zippy", 20);

myCar.CrankTunes(true);

for (int i = 0; i < 10; i++) myCar.Accelerate(10);

Console.ReadLine();

}

we would see the output displayed in Figure 7-1.

Figure 7-1. The Car in action

Throwing a Generic Exception

Now that we have a functional Car type, I’ll illustrate the simplest way to throw an exception. The current implementation of Accelerate() simply displays an error message if the caller attempts to speed up the Car beyond its upper limit.

To retrofit this method to throw an exception if the user attempts to speed up the automobile after it has met its maker, you want to create and configure a new instance of the System.Exception class, setting the value of the read-only Message property via the class constructor. When you wish to send the error object back to the caller, make use of the C# throw keyword. Here is the relevant code update to the Accelerate() method:

// This time, throw an exception if the user speeds up beyond MaxSpeed. public void Accelerate(int delta)

{

if (carIsDead)

Console.WriteLine("{0} is out of order...", petName); else

{

currSpeed += delta;

if (currSpeed >= MaxSpeed)

{

carIsDead = true; currSpeed = 0;

// Use the "throw" keyword to raise an exception.

throw new Exception(string.Format("{0} has overheated!", petName));

}

else

Console.WriteLine("=> CurrSpeed = {0}", currSpeed);

}

}

Before examining how a caller would catch this exception, a few points of interest. First of all, when you are throwing an exception, it is always up to you to decide exactly what constitutes the error in question, and when it should be thrown. Here, you are making the assumption that if the program attempts to increase the speed of a car that has expired, a System.Exception type should be thrown to indicate the Accelerate() method cannot continue (which may or may not be a valid assumption).

Alternatively, you could implement Accelerate() to recover automatically without needing to throw an exception in the first place. By and large, exceptions should be thrown only when a more terminal condition has been met (for example, not finding a necessary file, failing to connect to a database, and whatnot). Deciding exactly what constitutes throwing an exception is a design issue you must always contend with. For our current purposes, assume that asking a doomed automobile to increase its speed justifies a cause to throw an exception.

Catching Exceptions

Because the Accelerate() method now throws an exception, the caller needs to be ready to handle the exception should it occur. When you are invoking a method that may throw an exception, you make use of a try/catch block. Once you have caught the exception object, you are able to invoke the members of the System.Exception type to extract the details of the problem. What you do with this data is largely up to you. You may wish to log this information to a report file, write the data to the Windows event log, e-mail a system administrator, or display the problem to the end user. Here, you will simply dump the contents to the console window:

// Handle the thrown exception. static void Main(string[] args)

{

Console.WriteLine("***** Simple Exception Example *****");

Console.WriteLine("=> Creating a car and stepping on it!"); Car myCar = new Car("Zippy", 20);

myCar.CrankTunes(true);

//Speed up past the car's max speed to

//trigger the exception.

try

{

for(int i = 0; i < 10; i++) myCar. Accelerate(10);

226 CHAPTER 7 ■ UNDERSTANDING STRUCTURED EXCEPTION HANDLING

}

catch(Exception e)

{

Console.WriteLine("\n*** Error! ***");

Console.WriteLine("Method: {0}", e.TargetSite); Console.WriteLine("Message: {0}", e.Message); Console.WriteLine("Source: {0}", e.Source);

}

// The error has been handled, processing continues with the next statement.

Console.WriteLine("\n***** Out of exception logic *****");

Console.ReadLine();

}

In essence, a try block is a section of statements that may throw an exception during execution. If an exception is detected, the flow of program execution is sent to the appropriate catch block. On the other hand, if the code within a try block does not trigger an exception, the catch block is skipped entirely, and all is right with the world. Figure 7-2 shows a test run of this program.

Figure 7-2. Dealing with the error using structured exception handling

As you can see, once an exception has been handled, the application is free to continue on from the point after the catch block. In some circumstances, a given exception may be critical enough to warrant the termination of the application. However, in a good number of cases, the logic within the exception handler will ensure the application will be able to continue on its merry way (although it may be slightly less functional, such as the case of not being able to connect to a remote data source).

Configuring the State of an Exception

Currently, the System.Exception object configured within the Accelerate() method simply establishes a value exposed to the Message property (via a constructor parameter). As shown previously in Table 7-1, however, the Exception class also supplies a number of additional members (TargetSite, StackTrace, HelpLink, and Data) that can be useful in further qualifying the nature of the problem. To spruce up our current example, let’s examine further details of these members on a case-by-case basis.

228 CHAPTER 7 ■ UNDERSTANDING STRUCTURED EXCEPTION HANDLING

The StackTrace Property

The System.Exception.StackTrace property allows you to identify the series of calls that resulted in the exception. Be aware that you never set the value of StackTrace as it is established automatically at the time the exception is created. To illustrate, assume you have once again updated your catch logic:

catch(Exception e)

{

...

Console.WriteLine("Stack: {0}", e.StackTrace);

}

If you were to run the program, you would find the following stack trace is printed to the console (your line numbers and file paths may differ, of course):

Stack: at SimpleException.Car.Accelerate(Int32 delta)

in c:\MyApps\SimpleException\car.cs:line 65 at SimpleException.Program.Main() in c:\MyApps\SimpleException\Program.cs:line 21

The string returned from StackTrace documents the sequence of calls that resulted in the throwing of this exception. Notice how the bottommost line number of this string identifies the first call in the sequence, while the topmost line number identifies the exact location of the offending member. Clearly, this information can be quite helpful during the debugging or logging of a given application, as you are able to “follow the flow” of the error’s origin.

The HelpLink Property

While the TargetSite and StackTrace properties allow programmers to gain an understanding of a given exception, this information is of little use to the end user. As you have already seen, the System.Exception.Message property can be used to obtain human-readable information that may be displayed to the current user. In addition, the HelpLink property can be set to point the user to a specific URL or standard Windows help file that contains more detailed information.

By default, the value managed by the HelpLink property is an empty string. If you wish to

fill this property with a more interesting value, you will need to do so before throwing the System. Exception type. Here are the relevant updates to the Car.Accelerate() method:

public void Accelerate(int delta)

{

if (carIsDead)

Console.WriteLine("{0} is out of order...", petName); else

{

currSpeed += delta;

if (currSpeed >= MaxSpeed)

{

carIsDead = true; currSpeed = 0;

//We need to call the HelpLink property, thus we need to

//create a local variable before throwing the Exception object.

Exception ex =

new Exception(string.Format("{0} has overheated!", petName)); ex.HelpLink = "http://www.CarsRUs.com";

throw ex;

}

else

Console.WriteLine("=> CurrSpeed = {0}", currSpeed);

}

}

The catch logic could now be updated to print out this help link information as follows:

catch(Exception e)

{

...

Console.WriteLine("Help Link: {0}", e.HelpLink);

}

The Data Property

The Data property of System.Exception allows you to fill an exception object with relevant auxiliary information (such as a time stamp or what have you). The Data property returns an object implementing an interface named IDictionary, defined in the System.Collections namespace. Chapter 9 examines the role of interface-based programming as well as the System.Collections namespace. For the time being, just understand that dictionary collections allow you to create a set of values that are retrieved using a specific key. Observe the next update to the Car.Accelerate() method:

public void Accelerate(int delta)

{

if (carIsDead)

Console.WriteLine("{0} is out of order...", petName); else

{

currSpeed += delta;

if (currSpeed >= MaxSpeed)

{

carIsDead = true; currSpeed = 0;

//We need to call the HelpLink property, thus we need

//to create a local variable before throwing the Exception object. Exception ex =

new Exception(string.Format("{0} has overheated!", petName)); ex.HelpLink = "http://www.CarsRUs.com";

//Stuff in custom data regarding the error. ex.Data.Add("TimeStamp",

string.Format("The car exploded at {0}", DateTime.Now)); ex.Data.Add("Cause", "You have a lead foot.");

throw ex;

}

else

Console.WriteLine("=> CurrSpeed = {0}", currSpeed);

}

}

To successfully enumerate over the key/value pairs, you first must make sure to specify a using directive for the System.Collections namespace, given we will make use of a DictionaryEntry type in the file containing the class implementing your Main() method:

using System.Collections;

230 CHAPTER 7 ■ UNDERSTANDING STRUCTURED EXCEPTION HANDLING

Next, we need to update the catch logic to test that the value returned from the Data property is not null (the default value). After this point, we make use of the Key and Value properties of the DictionaryEntry type to print the custom data to the console:

catch (Exception e)

{

...

// By default, the data field is empty, so check for null.

Console.WriteLine("\n-> Custom Data:"); if (e.Data != null)

{

foreach (DictionaryEntry de in e.Data) Console.WriteLine("-> {0}: {1}", de.Key, de.Value);

}

}

With this, we would now find the update shown in Figure 7-4.

Figure 7-4. Obtaining programmer-defined data

The Data property is very useful in that it allows us to pack in custom information regarding the error at hand without requiring us to build a brand-new class type extending the Exception base class (which, prior to .NET 2.0, was our only option!). As helpful as the Data property may be, however, it is still common for .NET developers to build strongly typed exception classes, which account for custom data using strongly typed properties.

This approach allows the caller to catch a specific Exception-derived type, rather than having to dig into a data collection to obtain additional details. To understand how to do so, we need to examine the distinction between system-level and application-level exceptions.

■Source Code The SimpleException project is included under the Chapter 7 subdirectory.

System-Level Exceptions (System.SystemException)

The .NET base class libraries define many classes which ultimately derive from System.Exception. For example, the System namespace defines core error objects such as ArgumentOutOfRangeException,

IndexOutOfRangeException, StackOverflowException, and so forth. Other namespaces define exceptions that reflect the behavior of that namespace (e.g., System.Drawing.Printing defines printing exceptions, System.IO defines IO-based exceptions, System.Data defines database-centric exceptions, and so forth).

Exceptions that are thrown by the .NET platform are (appropriately) called system exceptions. These exceptions are regarded as nonrecoverable, fatal errors. System exceptions derive directly from a base class named System.SystemException, which in turn derives from System.Exception (which derives from System.Object):

public class SystemException : Exception

{

//Various constructors.

}

Given that the System.SystemException type does not add any additional functionality beyond a set of custom constructors, you might wonder why SystemException exists in the first place. Simply put, when an exception type derives from System.SystemException, you are able to determine that the .NET runtime is the entity that has thrown the exception, rather than the code base of the executing application. You can verify this quite simply using the is keyword:

// True! NullReferenceException is-a SystemException.

NullReferenceException nullRefEx = new NullReferenceException();

Console.WriteLine("NullReferenceException is-a SystemException? : {0}", nullRefEx is SystemException);

Application-Level Exceptions (System.ApplicationException)

Given that all .NET exceptions are class types, you are free to create your own application-specific exceptions. However, due to the fact that the System.SystemException base class represents exceptions thrown from the CLR, you may naturally assume that you should derive your custom exceptions from the System.Exception type. While you could do so, best practice dictates that

you instead derive from the System.ApplicationException type:

public class ApplicationException : Exception

{

//Various constructors.

}

Like SystemException, ApplicationException does not define any additional members beyond a set of constructors. Functionally, the only purpose of System.ApplicationException is to identify the source of the error. When you handle an exception deriving from System.ApplicationException, you can assume the exception was raised by the code base of the executing application, rather than by the .NET base class libraries or .NET runtime engine.

Building Custom Exceptions, Take One

While you can always throw instances of System.Exception to signal a runtime error (as shown in our first example), it is sometimes advantageous to build a strongly typed exception that represents the unique details of your current problem. For example, assume you wish to build a custom exception (named CarIsDeadException) to represent the error of speeding up a doomed automobile. The first step is to derive a new class from System.ApplicationException (by convention, all exception classes end with the “Exception” suffix; in fact, this is a .NET best practice).