So we finally spotted the problem, and stopped it from causing trouble. How do we find out what is wrong? Well, first we should take a look at the error message. That tells us that it has something to do with rotating the turtle, which gives us a bit of a clue. The easiest way to see what is really going on, though, might be to set a breakpoint in our error handler and see what state the system is in when the error occurs.

To set a breakpoint, we can put the cursor on the line where we want to break into the debugger, and press F9. Figure 6-1 shows the code with a breakpoint set.

Figure 6-1. Code with a breakpoint set

If we run this now, the application will break into the debugger when we hit our error handler. If we press Ctrl-Alt-C, we can inspect the call stack to see where we went wrong, as shown in Figure 6-2.

Figure 6-2. Call stack, broken in the error handler

As you can see, there’s not an awful lot to help us; we lost context in which the error occurred because we returned out of the method that had the actual problem, and wound back up to our calling function.

It isn’t completely useless—we now know which call had the problem (this time), so we can put a breakpoint on the relevant line and run again; but what if this was a hard-to-reproduce, intermittent error? We may have lost our one chance this week to identify and fix the problem!

These are not the only problems with a return-value-based approach to error handling. What if we already need to use the return value on the method? We’re heading into the realm of “magic” values that mean an error has occurred, or we could add out or ref parameters to allow our method to return both a useful output and an error code.

And what about property setters; we don’t have the option of a return value, but we might well like to return an error of some kind if the value is out of range.

If you’re thinking “surely there has to be a better way,” you’re right. C# (like most modern languages) supports an alternative means of signaling errors: exceptions.

When we handled our return values, we had to propagate them up the call stack by hand, adding appropriate return values to each and every method, checking the result, and either passing it up or transforming and passing it as we go.

Exceptions, on the other hand, propagate up the stack automatically. If we don’t want to add a handler, we don’t have to, and the next call site up gets its chance instead, until eventually we pop out at the top of Main and either break into the debugger or Windows Error Handling steps in.

This means we can take a more structured approach to error handling—identifying points in our application control flow where we want to handle particular types of exceptions, and gathering our error-handling code into easily identified blocks.

The try, catch, and finally keywords help us to define those blocks (along with the ubiquitous braces).

In our example, we have no need to handle the potential errors from each and every call to RunFor separately. Instead, we can wrap the whole set into a single set of try, catch, and finally blocks, as shown in Example 6-14.

static void Main(string[] args)
{
    Turtle arthurTheTurtle = new Turtle {
        PlatformWidth = 0.0, PlatformHeight = 10.0, MotorSpeed = 5.0 };

    ShowPosition(arthurTheTurtle);

    try
    {
        // We want to proceed forwards
        arthurTheTurtle.LeftMotorState = MotorState.Running;
        arthurTheTurtle.RightMotorState = MotorState.Running;
        // For two seconds
        arthurTheTurtle.RunFor(2.0);

        ShowPosition(arthurTheTurtle);


        // Now, let's rotate clockwise for a bit
        arthurTheTurtle.RightMotorState = MotorState.Reversed;
        // PI / 2 seconds should do the trick
        arthurTheTurtle.RunFor(Math.PI / 2.0);

        ShowPosition(arthurTheTurtle);


        // And let's go into reverse
        arthurTheTurtle.RightMotorState = MotorState.Reversed;
        arthurTheTurtle.LeftMotorState = MotorState.Reversed;

        // And run for 5 seconds
        arthurTheTurtle.RunFor(5);

        ShowPosition(arthurTheTurtle);

        // Then rotate back the other way
        arthurTheTurtle.RightMotorState = MotorState.Running;
        // And run for PI/4 seconds to give us 45 degrees
        arthurTheTurtle.RunFor(Math.PI / 4.0);

        ShowPosition(arthurTheTurtle);

        // And finally drive backwards for a bit
        arthurTheTurtle.RightMotorState = MotorState.Reversed;
        arthurTheTurtle.LeftMotorState = MotorState.Reversed;
        arthurTheTurtle.RunFor(Math.Cos(Math.PI / 4.0));

        ShowPosition(arthurTheTurtle);
    }
    catch (InvalidOperationException e)
    {
        Console.WriteLine("Error running turtle:");
        Console.WriteLine(e.Message);
    }
    finally
    {
        Console.ReadKey();
    }
}

If any of the code in the try block throws an exception, the runtime looks to see if there are any catch blocks whose exception type matches the type of that exception. It matches successfully if the catch parameter is either of the same type, or of a less-derived (base) type than that of the exception.

You can have any number of catch blocks for different types of exceptions, and it will look through them in the order they are defined; the first one that matches wins (even if there is a “better” match farther down).

If it doesn’t find a suitable match, the exception will be propagated on up the call stack, just as though there was no try block.

To see how this works in practice, let’s quickly modify the code in Example 6-14 to catch Exception as well, as shown in Example 6-15.

try
{
 ...
}
catch (Exception e2)
{
    Console.WriteLine("Caught generic exception...");
}
catch (InvalidOperationException e)
{
    Console.WriteLine("Error running turtle:");
    Console.WriteLine(e.Message);
}
finally
{
    Console.WriteLine("Waiting in the finally block...");
    Console.ReadKey();
}

If you try to compile this, you’ll see the following error:

A previous catch clause already catches all exceptions of this or of a
super type ('System.Exception')

This occurs because Exception is an ancestor of InvalidOperationException, and the clause appears first in the list of catch blocks. If we switch those around, we compile successfully, as shown in Example 6-16.

try
{
 ...
}
catch (InvalidOperationException e)
{
    Console.WriteLine("Error running turtle:");
    Console.WriteLine(e.Message);
}
catch (Exception e2)
{
    Console.WriteLine("Caught generic exception...");
}
finally
{
    Console.WriteLine("Waiting in the finally block...");
    Console.ReadKey();
}

When the flow of control leaves the try block successfully, or the flow of control exits the last catch block if an exception occurred in the try block, the code in the finally block is executed. In other words, the code in the finally block is always executed, regardless of whether there was an exception.

If you designed your exception-handling code nicely, you’ll almost certainly use far more finally blocks than you do catch blocks. The finally block is a good place for cleaning up your resources, or winding back internal state if an error occurs, to ensure that your pre- and post conditions are still valid, whereas a catch block allows you to deal with an error condition you, as a client, understand in some way—even if it is only to present a message to the user (as in this case).

If we compile and run our code again, we’ll see the following output:

Arthur is at (0,0) and is pointing at angle 0.00 radians.
Arthur is at (0,10) and is pointing at angle 0.00 radians.
Error running turtle:
The PlatformWidth must be initialized to a value > 0.0
Waiting in the finally block...

Notice how the error-handling code is now consolidated neatly into clearly defined blocks, rather than scattered throughout our code, and we’ve been able to cut down substantially on the number of points of return from our method.

At the moment, we’re not handling any exceptions in our Turtle itself. Let’s imagine that our Turtle is being provided to clients in a library, and we (as the leading vendors of turtle simulators) want the library to do some internal logging when errors occur: maybe we have an opt-in customer experience program that sends telemetry back to our team.

We still want the errors to propagate up to the client for them to deal with; we just want to see them on the way past.

C# gives us the ability to catch, and then transparently rethrow, an exception, as shown in Example 6-17.

// Run the turtle for the specified duration
public void RunFor(double duration)
{
    try
    {

        if (LeftMotorState == MotorState.Stopped &&
            RightMotorState == MotorState.Stopped)
        {
            // If we are at a full stop, nothing will happen
            return;
        }

        // The motors are both running in the same direction
        // then we just drive
        if ((LeftMotorState == MotorState.Running &&
            RightMotorState == MotorState.Running) ||
            (LeftMotorState == MotorState.Reversed &&
            RightMotorState == MotorState.Reversed))
        {
            Drive(duration);
        }

        // The motors are running in opposite directions,
        // so we don't move, we just rotate about the
        // center of the rig
        if ((LeftMotorState == MotorState.Running &&
            RightMotorState == MotorState.Reversed) ||
            (LeftMotorState == MotorState.Reversed &&
            RightMotorState == MotorState.Running))
        {
            Rotate(duration);

        }
    }
    catch (Exception ex)
    {
        Console.WriteLine("Log message: " + ex.Message);
        // Rethrow
        throw;
    }
}

The first thing to notice is that we caught the base Exception type, having just said that we almost never do that. We want to log every exception, and because we’re rethrowing rather than eating it, we won’t simply ignore exceptions we weren’t expecting.

After we execute our handler code (just writing the message to the console in this case), we use the throw keyword, without any object, to rethrow the exception we just caught.

If you compile and run that, you’ll see the following output:

Arthur is at (0,0) and is pointing at angle 0.00 radians.
Arthur is at (0,10) and is pointing at angle 0.00 radians.
Log error: The PlatformWidth must be initialized to a value > 0.0
Error running turtle:
The PlatformWidth must be initialized to a value > 0.0
Waiting in the finally block

Notice that we get the output from both of the exception handlers.

That’s not the only way to throw from a catch block: it is perfectly reasonable to throw any exception from our exception handler! We often do this to wrap up an exception that comes from our implementation in another exception type that is more appropriate for our context. The original exception is not thrown away, but stashed away in the InnerException property of the new one, as shown in Example 6-18.

// Run the turtle for the specified duration
public void RunFor(double duration)
{
    try
    {

        if (LeftMotorState == MotorState.Stopped &&
            RightMotorState == MotorState.Stopped)
        {
            // If we are at a full stop, nothing will happen
            return;
        }

        // The motors are both running in the same direction
        // then we just drive
        if ((LeftMotorState == MotorState.Running &&
            RightMotorState == MotorState.Running) ||
            (LeftMotorState == MotorState.Reversed &&
            RightMotorState == MotorState.Reversed))
        {
            Drive(duration);
        }

        // The motors are running in opposite directions,
        // so we don't move, we just rotate about the
        // center of the rig
        if ((LeftMotorState == MotorState.Running &&
            RightMotorState == MotorState.Reversed) ||
            (LeftMotorState == MotorState.Reversed &&
            RightMotorState == MotorState.Running))
        {
            Rotate(duration);

        }
    }
    catch (InvalidOperationException iox)
    {
        throw new Exception("Some problem with the turtle...", iox);
    }
    catch (Exception ex)
    {
        // Log here
        Console.WriteLine("Log message: " + ex.Message);
        // Rethrow
        throw;
    }
}

Notice how we passed the exception to be wrapped as a parameter to the new exception when we constructed it. Let’s make a quick modification to the exception handler in Main to take advantage of this new feature (see Example 6-19).

static void Main(string[] args)
{
    Turtle arthurTheTurtle = new Turtle {
        PlatformWidth = 0.0, PlatformHeight = 10.0, MotorSpeed = 5.0 };

    ShowPosition(arthurTheTurtle);

    try
    {
       // ...
    }
    catch (InvalidOperationException e)
    {
        Console.WriteLine("Error running turtle:");
        Console.WriteLine(e.Message);
    }
    catch (Exception e1)
    {
        // Loop through the inner exceptions, printing their messages
        Exception current = e1;
        while (current != null)
        {
            Console.WriteLine(current.Message);
            current = current.InnerException;
        }
    }
    finally
    {
        Console.WriteLine("Waiting in the finally block");
        Console.ReadKey();
    }
}

If we compile and run again, we can see the following output, including the messages from both the outer and inner exceptions:

Arthur is at (0,0) and is pointing at angle 0.00 radians.
Arthur is at (0,10) and is pointing at angle 0.00 radians.
Some problem with the turtle has occurred
The PlatformWidth must be initialized to a value > 0.0
Waiting in the finally block

Clearly, wrapping an implementation-detail exception with something explicitly documented in our public contract can simplify the range of exception handlers you require. It also helps to encapsulate implementation details, as the exceptions you throw can be considered part of your contract.

On the other hand, are there any disadvantages to throwing a wrapped exception (or indeed rethrowing the original exception explicitly, rather than implicitly with throw;)? As programming tends to be a series of compromises, the answer is, as you might expect, yes.

If you explicitly (re)throw an exception, the call stack in the exception handler starts at the new throw statement, losing the original context in the debugger (although you can still inspect it in the inner exception in the object browser). This makes debugging noticeably less productive.

Because of this, you should consider carefully whether you need to wrap the exception, and always ensure that you implicitly (rather than explicitly) rethrow exceptions that you have caught and then wish to pass through.

It is worth clarifying exactly when the finally block gets executed, under a few edge conditions.

First, let’s see what happens if we run our example application outside the debugger. If we do that (by pressing Ctrl-F5) we’ll see that Windows Error Handling^[12] materializes, and presents the user with an error dialog before we actually hit our finally block at all! It is like the runtime has inserted an extra catch block in our own (top-level) exception handler, rather than percolating up another level (and hence out of our scope, invoking the code in the finally block).

And what happens when exceptions are thrown out of the exception handlers?

Let’s add a finally block to our RunFor method (see Example 6-20).

// Run the turtle for the specified duration
public void RunFor(double duration)
{
    try
    {
        // ...
    }
    catch (InvalidOperationException iox)
    {
        throw new Exception("Some problem with the turtle has occurred", iox);
    }
    catch (Exception ex)
    {
        // Log here
        Console.WriteLine("Log error: " + ex.Message);
        // Rethrow
        throw;
    }
    finally
    {
        Console.WriteLine("In the Turtle finally block");
    }
}

If you compile and run this code, you’ll see the following output:

Arthur is at (0,0) and is pointing at angle 0.00 radians.
In the Turtle finally block
Arthur is at (0,10) and is pointing at angle 0.00 radians.
In the Turtle finally block
Some problem with the turtle has occurred
The PlatformWidth must be initialized to a value > 0.0
Waiting in the finally block

So our finally block executes after the exception is thrown, but before it executes the exception handlers farther up the stack.

One important question remains: how did we know what exception type to catch from our code? Unlike some other languages (e.g., Java) there is no keyword which allows us to specify that a method can throw a particular exception. We have to rely on good developer documentation. The MSDN documentation for the framework itself carefully documents all the exceptions that can be thrown from its methods (and properties), and we should endeavor to do the same.

The .NET Framework provides a wide variety of exception types that you can catch (and often use). Let’s revisit Table 6-1 (the common error types) and see what is available for those situations (see Table 6-2).

Obviously, that’s a much abbreviated list, but it contains some of the most common exceptions you’ll see in real applications. One of the most useful that you’ll throw yourself is the ArgumentException. You can use that when parameters passed to your methods fail to validate.

Let’s make use of that in our RunFor method. Say that a “feature” of our turtle hardware is that it crashes and becomes unresponsive if we try to run it for zero seconds. We can work around this in our software by checking for this condition in the RunFor method, and throwing an exception if clients try this, as shown in Example 6-21.

public void RunFor(double duration)
{
    if (duration <= double.Epsilon)
    {
        throw new ArgumentException(
            "Must provide a duration greater than 0",
            "duration");
    }
    try
    {
        // ...
    }
    catch (InvalidOperationException iox)
    {
        throw new Exception("Some problem with the turtle has occurred", iox);
    }
    catch (Exception ex)
    {
        // Log here
        Console.WriteLine("Log error: " + ex.Message);
        // Rethrow
        throw;
    }
    finally
    {
        Console.WriteLine("In the Turtle finally block");
    }
}

The second parameter in this constructor should match the name of the parameter that is in error. The first represents the exception message.

The code in Example 6-22 updates Main, to sneak in an attempt to run it for zero seconds.

static void Main(string[] args)
{
    Turtle arthurTheTurtle = new Turtle {
        PlatformWidth = 0.0, PlatformHeight = 10.0, MotorSpeed = 5.0 };

    ShowPosition(arthurTheTurtle);

    try
    {
        arthurTheTurtle.RunFor(0.0);
    // ...
    }
    catch (InvalidOperationException e)
    {
        Console.WriteLine("Error running turtle:");
        Console.WriteLine(e.Message);
    }
    catch (Exception e1)
    {
        // Loop through the inner exceptions, printing their messages
        Exception current = e1;
        while (current != null)
        {
            Console.WriteLine(current.Message);
            current = current.InnerException;
        }
    }
    finally
    {
        Console.WriteLine("Waiting in the finally block");
        Console.ReadKey();
    }
}

If we compile and run, we’ll see the following output:

Arthur is at (0,0) and is pointing at angle 0.00 radians.
Must provide a duration greater than 0
Parameter name: duration
Waiting in the finally block

Notice how the error message automatically includes the details of the problem parameter.

You might want to create your own exceptions for a couple of reasons:

The first of these is the most problematic. You should think very carefully about whether your exception is really special, or whether you can just reuse an existing exception type.

When you introduce new exceptions, you’re asking clients to understand and deal with a new type of problem, and you’re expecting them to handle it in a special way. There are occasional instances of this, but more often the differences are in the context (i.e., that it was thrown from your code) rather than the exception itself (i.e., something was out of range, invalid, null, or unavailable, or it timed out).

Slightly more often, you provide custom exception types when you want to provide a convenient API over some additional information that comes along with the exception. The Exception.Data property we discussed earlier might be a better solution—it gives you somewhere to put information without needing to add a new kind of exception. But the convenience of a dedicated property might outweigh the costs of introducing a custom exception.

Finally, you might wish to create a custom exception class to allow you to conceptually group some subsystem’s exceptions together. DbException is an example of this in the .NET Framework; it represents the various errors that can occur when using a database. There are various specialized errors that derive from this, such as the SqlException thrown by the SQL Server subsystem, but the common base class enables you to write a single catch for all database errors, rather than having to handle provider-specific errors.

Again, you should think carefully about this before doing it: what client exception-handling scenarios are you enabling, and why do you need the custom type?

However, having been through all of this, creating your own exception type is very simple. Let’s create a TurtleException for our exception wrapper (see Example 6-23).

[Serializable]
class TurtleException : Exception
{
    public TurtleException()
    {}

    public TurtleException(string message)
        : base(message)
    { }

    public TurtleException(string message, Exception innerException)
        : base(message, innerException)
    {}

    // For serialization support
    protected TurtleException(SerializationInfo info, StreamingContext context)
        : base(info, context)
    {}
}

The first thing to notice is that we derive from Exception.

If you’ve plowed through the MSDN documentation you might have noticed the ApplicationException type, which derives from Exception, and was provided as a base class for application-defined exceptions. Why, you might ask, are we not deriving from ApplicationException?

Well, ApplicationException adds no functionality to Exception, and the .NET designers could not come up with a scenario where it was useful to catch ApplicationException (as opposed to Exception). Sadly, they only realized this after .NET 1.0 had shipped, so it is in the library, but it is now deprecated. You should neither derive from nor catch ApplicationException.

Also, we provide a bunch of standard constructors: a default parameterless constructor, one that takes a message, and one that takes a message and an inner exception. Even if you add more properties to your own exception that you wish to initialize in the constructor, you should still provide constructors that follow this pattern (including the default, parameterless one).

The final constructor supports serialization. We do this because Exception itself is marked as a serializable class, which means that derived classes have to be too. This enables exceptions to cross appdomain boundaries.^[13] We’re just calling the base class’s constructor here. Because there is no constructor inheritance in C#, we need to provide a matching constructor which calls the one in our base. If we didn’t do this, any code that polymorphically used our TurtleException as its base Exception might break.