This section examines how to handle error reporting via a mechanism known as exception handling. With exception handling, a method can pass information about an error to a calling method without using a return value or explicitly providing any parameters to do so. Listing 5.26 with Output 5.10 contains a slight modification to Listing 1.16—the HeyYou program from Chapter 1. Instead of requesting the last name of the user, it prompts for the user’s age.
The return value from System.Console.ReadLine() is stored in a variable called ageText and is then passed to a method with the int data type, called Parse(). This method is responsible for taking a string value that represents a number and converting it to an int type.
C# requires that every non-null value have a well-defined type associated with it. Therefore, not only the data value but also the type associated with the data is important. A string value of “42”, therefore, is distinctly different from an integer value of 42. The string is composed of the two characters 4 and 2, whereas the int is the number 42.
Given the converted string, the final System.Console.WriteLine() statement will print the age in months by multiplying the age value by 12.
But what happens if the user does not enter a valid integer string? For example, what happens if the user enters “forty-two”? The Parse() method cannot handle such a conversion. It expects the user to enter a string that contains only numerical digits. If the Parse() method is sent an invalid value, it needs some way to report this fact back to the caller.
To indicate to the calling method that the parameter is invalid, int.Parse() will throw an exception. Throwing an exception halts further execution in the current control flow and jumps into the first code block within the call stack that handles the exception.
Since you have not yet provided any such handling, the program reports the exception to the user as an unhandled exception. Assuming there is no registered debugger on the system, console applications will display the error on the console with a message such as that shown in Output 5.11.
Obviously, such an error is not particularly helpful. To fix this, it is necessary to provide a mechanism that handles the error, perhaps reporting a more meaningful error message back to the user.
This process is known as catching an exception. The syntax is demonstrated in Listing 5.27, and the output appears in Output 5.12.
To begin, surround the code that could potentially throw an exception (age = int.Parse()) with a try block. This block begins with the try keyword. It indicates to the compiler that the developer is aware of the possibility that the code within the block might throw an exception, and if it does, one of the catch blocks will attempt to handle the exception.
One or more catch blocks (or the finally block) must appear immediately following a try block. The catch block header (see “Advanced Topic: General Catch” later in this chapter) optionally allows you to specify the data type of the exception. As long as the data type matches the exception type, the catch block will execute. If, however, there is no appropriate catch block, the exception will fall through and go unhandled as though there were no exception handling. The resultant control flow appears in Figure 5.1.
For example, assume the user enters “forty-two” for the age in the previous example. In this case, int.Parse() will throw an exception of type System.FormatException, and control will jump to the set of catch blocks. (System.FormatException indicates that the string was not of the correct format to be parsed appropriately.) Since the first catch block matches the type of exception that int.Parse() threw, the code inside this block will execute. If a statement within the try block threw a different exception, the second catch block would execute because all exceptions are of type System.Exception.
If there were no System.FormatException catch block, the System.Exception catch block would execute even though int.Parse throws a System.FormatException. This is because a System.FormatException is also of type System.Exception. (System.FormatException is a more specific implementation of the generic exception, System.Exception.)
The order in which you handle exceptions is significant. Catch blocks must appear from most specific to least specific. The System.Exception data type is least specific, so it appears last. System.FormatException appears first because it is the most specific exception that Listing 5.27 handles.
Regardless of whether control leaves the try block normally or because the code in the try block throws an exception, the finally block of code executes after control leaves the try-protected region. The purpose of the finally block is to provide a location to place code that will execute regardless of how the try/catch blocks exit—with or without an exception. Finally blocks are useful for cleaning up resources, regardless of whether an exception is thrown. In fact, it is possible to have a try block with a finally block and no catch block. The finally block executes regardless of whether the try block throws an exception or whether a catch block is even written to handle the exception. Listing 5.28 demonstrates the try/finally block, and Output 5.13 shows the results.
The attentive reader will have noticed something interesting here: The runtime first reported the unhandled exception and then ran the finally block. What explains this unusual behavior?
First, the behavior is legal because when an exception is unhandled, the behavior of the runtime is implementation defined—any behavior is legal! The runtime chooses this particular behavior because it knows before it chooses to run the finally block that the exception will be unhandled; the runtime has already examined all of the activation frames on the call stack and determined that none of them is associated with a catch block that matches the thrown exception.
As soon as the runtime determines that the exception will be unhandled, it checks whether a debugger is installed on the machine, because you might be the software developer who is analyzing this failure. If a debugger is present, it offers the user the chance to attach the debugger to the process before the finally block runs. If there is no debugger installed or if the user declines to debug the problem, the default behavior is to print the unhandled exception to the console and then see if there are any finally blocks that could run. Due to the “implementation-defined” nature of the situation, the runtime is not required to run finally blocks in this situation; an implementation may choose to do so or not.
All objects thrown as exceptions derive from System.Exception. (Objects thrown from other languages that do not derive from System.Exception are automatically “wrapped” by an object that does.) Therefore, they can be handled by the catch(System.Exception exception) block. It is preferable, however, to include a catch block that is specific to the most derived type (e.g., System.FormatException), because then it is possible to get the most information about an exception and handle it less generically. In so doing, the catch statement that uses the most derived type can handle the exception type specifically, accessing data related to the exception thrown and avoiding conditional logic to determine what type of exception occurred.
Therefore, C# enforces the rule that catch blocks appear from most derived to least derived. For example, a catch statement that catches System.Exception cannot appear before a statement that catches System.FormatException because System.FormatException derives from System.Exception.
A method could throw many exception types. Table 5.2 lists some of the more common ones within the framework.
Exception Type |
Description |
System.Exception |
The “base” exception from which all other exceptions derive. |
System.ArgumentException |
Indicates that one of the arguments passed into the method is invalid. |
System.ArgumentNullException |
Indicates that a particular argument is null and that this is not a valid value for that parameter. |
System.ApplicationException |
To be avoided. The original idea was that you might want to have one kind of handling for system exceptions and another for application exceptions, which, although plausible, doesn’t actually work well in the real world. |
System.FormatException |
Indicates that the string format is not valid for conversion. |
System.IndexOutOfRangeException |
Indicates that an attempt was made to access an array or other collection element that does not exist. |
System.InvalidCastException |
Indicates that an attempt to convert from one data type to another was not a valid conversion. |
System.InvalidOperationException |
Indicates that an unexpected scenario has occurred such that the application is no longer in a valid state of operation. |
System.NotImplementedException |
Indicates that although the method signature exists, it has not been fully implemented. |
System.NullReferenceException |
Thrown when code tries to find the object referred to by a reference that is null. |
System.ArithmeticException |
Indicates an invalid math operation, not including divide by zero. |
System.ArrayTypeMismatchException |
Occurs when attempting to store an element of the wrong type into an array. |
System.StackOverflowException |
Indicates an unexpectedly deep recursion. |
It is possible to specify a catch block that takes no parameters, as shown in Listing 5.29.
A catch block with no data type, called a general catch block, is equivalent to specifying a catch block that takes an object data type—for instance, catch(object exception){...}. For this reason, a warning is triggered stating that the catch block already exists; hence the #pragma warning disable directive.
Because all classes ultimately derive from object, a catch block with no data type must appear last.
General catch blocks are rarely used because there is no way to capture any information about the exception. In addition, C# doesn’t support the ability to throw an exception of type object. (Only libraries written in languages such as C++ allow exceptions of any type.)
C# allows developers to throw exceptions from their code, as demonstrated in Listing 5.30 and Output 5.14.
As the comments in Listing 5.30 depict, throwing an exception causes execution to jump from where the exception is thrown into the first compatible catch block (Catch 1).10 In this case, the second catch block handles the exception and writes out an error message. In Listing 5.30, there is no finally block, so following the WriteLine() method of Catch 1, execution falls through to the Console.WriteLine() statement following the try/catch block (after the Post Catch comment).
To throw an exception, it is necessary to have an instance of an exception. Listing 5.30 creates an instance using the keyword new followed by the type of the exception. Most exception types allow a message to be specified for the exception’s construction parameter, so that when the exception occurs, the message can be retrieved.
Sometimes a catch block will trap an exception but be unable to handle it appropriately or fully. In these circumstances, a catch block can rethrow the exception using the throw statement without specifying any exception, as shown in Listing 5.31.
In Listing 5.31, the throw statement is “empty” rather than specifying that the exception referred to by the exception variable is to be thrown. This illustrates a subtle difference: throw; preserves the call stack information in the exception, whereas throw exception; replaces that information with the current call stack information. For debugging purposes, it is usually better to know the original call stack. Of course, this is allowed only in a catch statement where the caught exception can be determined.
When nullability reference types are enabled, the compiler will make a best effort to identify when there is the possibility of a nullable argument passed as a non-nullable argument. If you assign a possible null value to a non-nullable argument, the compiler will issue a warning stating that you are attempting to convert a possible null value to a non-nullable argument. Assuming you address all such warnings appropriately, the compiler will catch most of the cases. However, if the caller is outside of your control (such as from a library you didn’t write), doesn’t turn on nullable reference types, ignores the warnings, or invokes the method from C# 7.0 or earlier, there is nothing preventing a null argument even though the parameter is declared as non-nullable. For this reason, the best practice is to check that any public non-nullable reference types are not null. With .NET 6.0 you can use a conditional if (is null) check:
if (is null) throw new ArgumentNullException(...)
You can accomplish this in a single statement using the null coalescing assignment operator with a throw ArgumentNullException expression if the parameter value is null (see Listing 5.32).
With .NET 7.0, you can use the ArgumentNullException.ThrowIfNull() method (see Listing 5.33).
Internally, the ArgumentNullException.ThrowIfNull() method also throws the ArgumentNullException.
There are obviously a myriad of other type constraints that a method may have on its parameters. Perhaps a string argument should not be an empty string, should not be comprised only of whitespace, or must have “HTTPS” as a prefix. Listing 5.34 displays the full DownloadSSSL() method, demonstrating this validation.
When using .NET 7.0 or higher, you can rely on the ArgumentException.ThrowIfNullOrEmpty() method to check for both null and an empty string. And, if you invoke the string.Trim() method when invoking ThrowIfNullOrEmpty(), you can throw an exception if the argument content is only whitespace. (Admittedly, the exception message will not indicate whitespace only is invalid.) The equivalent code for .NET 6.0 or earlier is shown in the else directive.
If the null, empty, and whitespace validation pass, Listing 5.34 has an if statement that checks for the “HTTPS” prefix. If the validation fails, the resulting code throws an ArgumentException, with a custom message describing the problem.
When the parameter fails validation, it is necessary to throw an exception—generally of type ArgumentException() or ArgumentNullException(). Both exceptions take an argument of type string called paramName that identifies the name of the parameter that is invalid. In Listing 5.33, we use the nameof operator11 for this argument. The nameof operator takes an identifier, like the httpsUrl variable, and returns a string representation of that name—in this case, "httpsUrl".
The advantage of using the nameof operator is that if the identifier name changes, then refactoring tools will automatically change the argument to nameof as well. If no refactoring tool is used, the code will no longer compile, forcing the developer to change the argument manually, which is preferable because the former value would presumably be invalid. The result is that nameof will even check for spelling errors. The resulting guideline is: DO use nameof for the paramName argument passed into exceptions such as ArgumentException and ArgumentNullException that take such a parameter. For more information, see Chapter 18.
Developers should avoid throwing exceptions for expected conditions or normal control flow. For example, developers should not expect users to enter valid text when specifying their age.12 Therefore, instead of relying on an exception to validate data entered by the user, developers should provide a means of checking the data before attempting the conversion. (Better yet, they should prevent the user from entering invalid data in the first place.) Exceptions are designed specifically for tracking exceptional, unexpected, and potentially fatal situations. Using them for an unintended purpose such as expected situations will cause your code to be hard to read, understand, and maintain.
Consider, for example, the int.Parse() method we used in Chapter 2 to convert a string to an integer. In this scenario, the code converted user input that was expected to not always be a number. One of the problems with the Parse() method is that the only way to determine whether the conversion will be successful is to attempt the cast and then catch the exception if it doesn’t work. Because throwing an exception is a relatively expensive operation, it is better to attempt the conversion without exception handling. Toward this effort, it is preferable to use one of the TryParse() methods, such as int.TryParse(). It requires the use of the out keyword because the return from the TryParse() function is a bool rather than the converted value. Listing 5.35 is a code snippet that demonstrates the conversion using int.TryParse().
With the TryParse() method, it is no longer necessary to include a try/catch block simply for the purpose of handling the string-to-numeric conversion.
Another factor in favor of avoiding exceptions for expected scenarios is performance. Like most languages, C# incurs a slight performance hit when throwing an exception—taking microseconds compared to the nanoseconds most operations take. This delay is generally not noticeable in human time—except when the exception goes unhandled. For example, when Listing 5.26 is executed and the user enters an invalid age, the exception is unhandled and there is a noticeable delay while the runtime searches the environment to see whether there is a debugger to load. Fortunately, slow performance when a program is shutting down isn’t generally a factor to be concerned with.
________________________________________