About try blocks

Think of using the try block as putting the C# runtime on alert. The keyword is basically saying that the runtime should try to execute the code with the idea that it might not work. Exceptions bubble up through the code until the exception encounters a catch block or the application ends.

When working with a try block, make the code within it specific to a particular task or exception. Keep the try block as short as possible to reduce debugging time and to make it more likely that the code can recover from the exception. Use multiple short try blocks rather than trying to encompass all the code that could generate an exception within a single try block. Using a single large try block is akin to trying to eat an entire hero sandwich in a single bite: You might succeed, but you won't enjoy it, and there is always a mess to clean up later.

About catch blocks

A try block is usually followed immediately by the keyword catch, which is followed by the catch keyword's block. Control passes to the catch block in the event of an error anywhere within the try block. The argument to the catch block is an object of class Exception or, more likely, a subclass of Exception as shown here:

catch (Exception e)
{
// Display the error
Console.WriteLine(e.ToString());
}

If your catch doesn't need to access any information from the exception object it catches, you can specify only the exception type:

catch (SomeException) // No object specified here (no "Exception e")
{
// Do something that doesn't require access to exception object.
}

However, a catch block doesn’t have to have arguments: A bare catch catches any exception, equivalent to catch(Exception):

catch
{
}

Make catch blocks as specific as possible to reduce the work required to handle them and to make recovery more likely. In addition, you can stack catch blocks to enable you to handle exceptions as specifically as possible, with the most specific exception listed first. For example, in the following catch blocks, the ArgumentOutOfRangeException is the most specific exception, followed by ArgumentException, and finally the generic Exception:

catch (ArgumentOutOfRangeException e)
{
…Some remediation code to try.
}
catch (ArgumentException e)
{
…Some more remediation code to try.
}
catch (Exception e)
{
…Some last ditch remediation code to try.
}

After C# finds an exception handler that will address the exception, it ignores the other catch blocks, which is why you need the most specific exception listed first.

About finally blocks

A finally block, if you supply one, runs regardless of the following:

• Whether the try block throws an exception
• The code uses a break or continue to jump out of the block
• There is a return statement to exit the method containing the block

The finally block is called after a successful try or after a catch. You can use finally even if you don't have a catch. For example, you use the finally block to clean up before moving on so that files aren't left open. A common use of finally is to clean up after the code in the try block, regardless of whether an exception occurs. So you often see code that looks like this:

try
{
…
}
finally
{
// Clean up code, such as close a file opened in the try block.
}

In fact, you should use finally blocks liberally — only one per try. A finally block won't execute under these conditions:

• The program terminates because a fatal exception isn’t handled.
• The try block encounters a StackOverflowException, OutOfMemoryException, or ExecutingEngineException.
• An external application kills the process in which the finally block appears.

A method can have multiple try…catch handlers. You can even nest a try…catch inside a try, a try…catch inside a catch, or a try…catch inside a finally — or all the above. (And you can substitute try/finally for all the above.)

What happens when an exception is thrown

When an exception occurs, a variation of this sequence of events takes place:

1. An exception is thrown.

   Somewhere deep in the bowels of SomeOtherMethod(), an error occurs. Always at the ready, the method reports a runtime error with the throw of an Exception object back to the first block that knows enough to catch and handle it.

   Note that because an exception is a runtime error, not a compile error, it occurs as the program executes. So an error can occur after you release your masterpiece to the public. Oops!

2. C# “unwinds the call stack,” looking for a catch block.

   The exception works its way back to the calling method, and then to the method that called that method, and so on, even all the way to the top of the program in Main() if no catch block is found to handle the exception. Figure 9-1 shows the path that's followed as C# searches for an exception handler.

   

3. If an appropriate catch block is found, it executes.

   An appropriate catch block is one that's looking for the right exception class (or any of its derived classes — Exception will handle any exception, but ArgumentOutOfRangeException will handle exceptions only when the argument is out of range). This catch block might do any of a number of things. As the stack unwinds, if a given method doesn't have enough context — that is, doesn’t know enough — to correct the exceptional condition, it simply doesn’t provide a catch block for that exception. The right catch may be higher up the stack.

4. If a finally block accompanies the try block, it executes, whether an exception was caught or not.

   The finally is called before the stack unwinds to the next-higher method in the call chain. All finally blocks anywhere up the call chain also execute.

5. If no appropriate catch block is found anywhere, the program generally crashes.

   If C# gets to Main() and doesn't find a catch block there, the user sees an “unhandled exception” message, and the program normally exits unless the underlying operating system can supply a fix (which is rare). This is a crash. However, you can deal with exceptions not caught elsewhere by using an exception handler in Main(). See the section “Grabbing Your Last Chance to Catch an Exception,” later in this chapter.

The exception mechanism provides you with these benefits:

• Exceptions provide an expressive model — one that lets you express a wide variety of error-handling strategies.
• An exception object carries a lot of information with it, thus aiding in debugging.
• Exceptions lead to more readable code because you can see what could go wrong at a glance — and less code because you spend less time trying to figure out how to fix errors.
• Exceptions are consistent, and a consistent model promotes understanding.

C# provides mechanisms to support other error-handling methods that you will encounter when working with the underlying operating system directly. This book doesn't discuss such techniques, so you see exception handling as the only error-handling method. However, you can read more about interacting with the underlying Win32 API at https://docs.microsoft.com/en-us/windows/apps/desktop/modernize/desktop-to-uwp-enhance, which is an advanced programming technique best left to people with a desire to slowly drive themselves nuts in pursuit of they know not what.

Throwing Exceptions Yourself

If code supplied with C# can throw exceptions, so can you. To throw an exception when you detect an error worthy of an exception, use the throw keyword:

throw new ArgumentException("Don't argue with me!");

You have as much right to throw things as anybody. Because C# has no awareness of your custom BadHairDayException, who will throw it but you?

If one of the .NET predefined exceptions fits your situation, throw it. Using a standard exception is always preferred because .NET already provides documentation for it and developers are used to using it. But if none fits, you can invent your own custom exception class.

.NET has some exception types that you should never catch: StackOverflowException, OutOfMemoryException, ExecutionEngineException, and a few more advanced items related to working with non-.NET code. These exceptions represent a kind of ultimate failure. For example, if you're out of stack space, as indicated by StackOverflowException, you simply don’t have any memory to continue executing the program. Given that exception handling occurs on the stack, you don’t even have enough memory to continue with the exception handling. Likewise, the OutOfMemoryException defines a condition in which your application is out of heap space (used for reference variables). And if the exception engine, ExecutionEngineException, isn't working at all, there isn’t any point in continuing because you have no way to handle this error.

Some questions to guide your planning

Several questions should be on your mind as you develop your program:

• What could go wrong? Ask this question about each bit of code you write.
• If it does go wrong, can I fix it? If so, you may be able to recover from the problem, and the program may be able to continue.
• Does the problem put user data at risk? If so, you must do everything in your power to keep from losing or damaging that data. Knowingly releasing code that can mangle user data is akin to software malpractice.
• Where should I put my exception handler for this problem? Trying to handle an exception in the method where it occurs may not be the best approach. Often, another method higher up in the chain of method calls has better information and may be able to do something more intelligent and useful with the exception. Put your try…catch there so that the try block surrounds the call that leads to the place where the exception can occur.
• Which exceptions should I handle? The answer is simple, all of them. There is never a good reason to leave exceptions unhandled in a way that leaves the user with one of those terrifying dialog boxes to gape at. If you can't provide a specific fix, at least exit from the application gracefully.
• What about exceptions that slip through the cracks and elude my handlers? Testing, testing, and more testing is the word of the day! Exceptions should never just sort of happen to anyone.
• What sort of input errors might my application see? Input errors happen from a wide range of sources, not just users. A file may contain bad data, or it might simply be missing or locked. Equipment, such as a network, used to retrieve data can malfunction. So, it’s not even enough to check for range and data type; you also need to check for issues such as missing sources.
• How robust (unbreakable) does my code need to be? You never know where your code is going to end up. You might have designed it as a simple utility, but if it does something useful, it could end up in an air-traffic-control system. With this need in mind, you need to make your code as bulletproof as possible every time you write code.

Guidelines for code that handles errors well

You should keep the questions in the previous section in mind as you work. These guidelines may help, too:

• Protect the user’s data at all costs. This is the Top Dog guideline. See the next bullet item.
• Don’t crash. Recover if you can, but be prepared to go down as gracefully as possible. Don’t let your program just squeak out a cryptic, geeky message and go belly up. Gracefully means that you provide clear messages containing as much helpful information as possible before shutting down. Users truly hate crashes. But you probably knew that.
• Don’t let your program continue running if you can’t recover from a problem. The program could be unstable or the user’s data left in an inconsistent state. When all is most certainly lost, you can display a message and call System.Environment.FailFast() to terminate the program immediately rather than throw an exception. It isn’t a crash — it’s deliberate.
• Treat class libraries differently from applications. In class libraries, let exceptions reach the caller, which is best equipped to decide how to deal with the problem. Don’t keep the caller in the dark about problems. But in applications, handle any exceptions you can. Your goal is to keep the code running if possible and protect the user’s data without putting a lot of inconsequential messages in the user’s face.

• Throw exceptions when, for any reason, a method can’t complete its task. The caller needs to know about the problem. (The caller may be a method higher up the call stack in your code or a method in code by another developer using your code.) If you check input values for validity before using them and they aren’t valid — such as an unexpected null value — fix them and continue if you can. Otherwise, throw an exception.

  Try to write code that doesn't need to throw exceptions — and correct bugs when you find them — rather than rely on exceptions to patch up the code. But use exceptions as your main method of reporting and handling errors.

• In most cases, don’t catch exceptions in a particular method unless you can handle them in a useful way, preferably by recovering from the error. Catching an exception that you can’t handle is like catching a wasp in your bare hand. Now what? Most methods don’t contain exception handlers.
• Test your code thoroughly, especially for any category of bad input you can think of. Can your method handle negative input? Zero? A very large value? An empty string? A null value? What could the user do to cause an exception? What fallible resources, such as files, databases, or URLs, does your code use? See the two previous bullet paragraphs.
• Catch the most specific exception you can. Don’t write many catch blocks for high-level exception classes such as Exception or ApplicationException.
• Always put a last-chance exception handler block in Main() — or wherever the “top” of your program is (except in reusable class libraries). You can catch type Exception in this block. Catch and handle the ones you can and let the last-chance exception handler pick up any stragglers. (The upcoming “Grabbing Your Last Chance to Catch an Exception” section explains last-chance handlers.)
• Don't use exceptions as part of the normal flow of execution. For example, don’t throw an exception as a way to get out of a loop or exit a method.
• Consider writing your own custom exception classes if they bring something to the table — such as more information to help in debugging or more meaningful error messages for users. You can also use custom exception classes to catch a less informational exception, such as DivideByZero, and provide a more informational exception, such as InvalidSalesTaxRate, to pass to the caller.

The rest of this chapter gives you the tools needed to follow these guidelines. For more information check out https://docs.microsoft.com/en-us/dotnet/csharp/fundamentals/exceptions/.

If a public method throws any exceptions that the caller may need to catch, those exceptions are part of your class's public interface. You need to document them, preferably with the “How to find out which methods throw which exceptions” section of Book 1, Chapter 9.

How to find out which methods throw which exceptions

To find out whether calling a particular method in the .NET class libraries, such as String.IndexOf() — or even one of your own methods — can throw an exception, consider these guidelines:

• Visual Studio provides immediate help with tooltips. When you hover the mouse pointer over a method name in the Visual Studio editor, a tooltip window lists not only the method’s parameters and return type but also the exceptions it can throw. If you need additional information, right-click the method name and choose Peek Definition from the context menu to see more specifics in a separate window.
• If you have used XML comments to comment your own methods, Visual Studio shows the information in those comments in its IntelliSense tooltips just as it does for .NET methods. If you documented the exceptions your method can throw (see the previous section), you see them in a tooltip, as part of autocomplete, and in the Object Browser. Place the <exception> line below your <summary> comment to make it show in the tooltip (see https://docs.microsoft.com/en-us/dotnet/csharp/codedoc for more details). Here is an example of XML comments for the Factorial() method in the FactorialException example:

  /// <summary>
/// public static int Factorial(int value)
/// <para>Return the factorial of the provided value.</para>
/// <example>
/// This shows a basic call.
/// <code>
/// input = 5;
/// int output = Factorial(input);
/// </code>
/// </example>
/// </summary>
/// <param name="value">The x! to find.</param>
/// <returns>Factorial value as int.</returns>
/// <exception cref="ArgumentOutOfRangeException">
/// The value must be greater than 0.
/// </exception>
/// <exception cref="OverflowException">
/// The x! is too large to compute.
/// </exception>

  When you hover your mouse over Factorial = MyMathFunctions.Factorial(Value);, you see the output shown in Figure 9-2.

• The C# Language Help files provide even more. When you look up a .NET method in C# Language Help, you find a list of exceptions that the method can throw, along with additional descriptions not provided via the yellow Visual Studio tooltip. To open the C# Language Help page for a given method, click the method name in your code and press F1. You can also supply similar help for your own classes and methods.

You should look at each of the exceptions you see listed, decide how likely it is to occur, and (if warranted for your program) guard against it using the techniques covered in the rest of this chapter.