Code Analysis Team Blog : Exceptions

How to Design Exception Hierarchies

David M. Kean — Thu, 01 Feb 2007 19:00:00 GMT

Krzysztof Cwalina, owner of the Framework Design Guidelines, has written a great post on designing exception hierarchies. He gives a great overview on the different categories of exceptions, which are placed under two main buckets he calls usage and system, and the right situations to throw them.

This post also goes hand-in-hand with some of the previous posts on this blog:

FAQ: What exception should I throw instead of the reserved exceptions that DoNotRaiseReservedExceptionTypes warns against?
FAQ: Why does FxCop warn against catch(Exception)? (Part 1, Part 2 and Part 3)

FAQ: What exception should I throw instead of the reserved exceptions that DoNotRaiseReservedExceptionTypes warns against?

David M. Kean — Mon, 22 Jan 2007 19:00:00 GMT

Throwing a general exception type such as System.Exception or System.SystemException in a library or Framework forces consumers to catch all exceptions, including unknown exceptions that they do not know how to handle (see FAQ: Why does FxCop warn against catch(Exception)? for reasons as to why this is bad).

Instead, either throw a more derived type that already exists in the Framework, or create your own type that derives from Exception.

The following list examples of when you should throw specific exceptions:

When validating a parameter (including the value parameter in the set accessor of a property) that:

is a null reference (Nothing in Visual Basic)
    throw System.ArgumentNullException

is outside of the allowable range of values (such as an index for a Collection/List)
    throw System.ArgumentOutOfRangeException (DO NOT throw System.IndexOutOfRangeException)

is outside the allowable values for a enum
    throw System.ComponentModel.InvalidEnumArgumentException

contains a format that not meet the parameter specifications of a method (such as the format string for ToString(String))
    throw System.FormatException

is otherwise invalid (such as an empty string)
    throw System.ArgumentException

When an operation is invalid for an object's current state:
throw System.InvalidOperationException

When an operation is performed on an object that has been disposed:
throw System.ObjectDisposedException

When an operation is not supported (such as in an overridden Stream.Write in a Stream opened for reading):
throw System.NotSupportedException (DO NOT throw System.NotImplementedException)

When a conversion would result in an overflow (such as in a explicit cast operator overload):
throw System.OverflowException

For all other situations, consider creating your own type that derives from Exception and throwing that.

Note: Exceptions that derive from ArgumentException (including ArgumentNullException, ArgumentException, ArgumentOutOfRangeException and InvalidEnumArgumentException), InvalidOperationException (including ObjectDisposedException) and NotSupportedException should only be thrown in situations that are avoidable (such as passing a null argument) and if thrown, would indicate a bug in the calling code. The Path class is not a good example of this, it incorrect throws ArgumentException to indicate that a path is incorrectly formed, however, it does not expose any methods that can help prevent this from occurring.

FAQ: Why does FxCop warn against catch(Exception)? - Part 3 [Nick Guerrera]

nicholg — Tue, 20 Jun 2006 07:16:00 GMT

This is the third installment in a three-part series on why FxCop warns against catch(Exception):
FAQ: Why does FxCop warn against catch(Exception)? - Part 1
FAQ: Why does FxCop warn against catch(Exception)? - Part 2
FAQ: Why does FxCop warn against catch(Exception)? - Part 3

I said from the beginning that this issue is controversial, and some of your feedback certainly confirms that. I want to make it clear that I respect everyone’s right to disagree with me, to exclude or disable the FxCop warning, and to implement a less rigid exception policy in their application code as they see fit. Furthermore, all of the opinions I’ve expressed are entirely my own and they represent a stricter interpretation of the Framework Design Guidelines than absolutely required. I believe strongly that the approach that I’ve outlined helps to find and fix defects sooner during development and testing and therefore helps to deliver more robust production software. Nevertheless, the choice to adopt a different strategy for your application is entirely yours.

On the other hand, as I mentioned in the previous post, this FxCop rule is of paramount importance for class library code. When class libraries call back to application code (via virtual methods, interface methods, events, or delegates), it is disastrous if they swallow or disguise the arbitrary exceptions that may be raised. (To see just how aggravating this can be for library consumers, witness the frustration with the WebBrowser control that readers expressed earlier.) Furthermore, class library code cannot make any assumptions about the implications of arbitrary exceptions for application code further up the call stack, so it must let them go so that the application can decide how to handle them.

With that said, let me now address the most recent comments with more of my own personal opinions. :)

Jeremy: “… I hope you do realize that a number of the recommendations you have given to people, myself included, basically amount to ‘let your app crash, your customers and business partners be damned.’ …"

No, I most certainly do not realize that, because it’s simply not true. Applications which catch only the precise exceptions that they are prepared to handle gracefully are easier to develop and maintain over the long run. When this strategy is combined with strong testing, the application will ship with fewer defects and there will be very few unhandled exceptions in the wild. The truth is that once an unexpected exception has been raised in your application, customers and partners are likely to suffer one way or another. The impact of corrupt program state can range from security vulnerability to plain incorrect output, which can end up costing customers more time and money than dealing with a crash.

Please don’t misconstrue this to mean that it’s ok to write sloppy software which crashes regularly in common cases. Clearly that’s unacceptable and I never said otherwise. However, the right way to avoid this fate is to design your software carefully, implement it methodically, and test it thoroughly.

Jeremy: “I think all of your readers know full well that applications need to be designed to fail fast and do so clearly in order to ease the diagnosis and correction of software defects.”

I’m glad that we agree that applications should be designed to “fail fast.” From my point of view, once an exception is raised in your application and you haven’t decided exactly how to handle it on its own terms, then the application has already “failed” and process termination represents the “fast” part of the equation. :)

Jeremy: “We do this, however, by modularizing software and testing it at an appropriate level of granularity, not by letting the whole app fall down in production.”

I do agree that it’s possible to sandbox components (for example, by using separate app-domains and ensuring that all shared data is immutable) such that the failure of a single component does not imply failure for the entire process. This then becomes, as you say, a question of granularity. You can think of each component as a mini-process, and then apply all of my arguments on a component-by-component basis. That is to say that when an isolated component throws an unexpected exception, its state must be discarded and it must be reloaded before it can reliably be consumed again. If your application is hardened in this way, then you would in fact need to catch (Exception) in all of the locations that you mentioned in your first comment in order to save the host process from termination. I missed that in my original reply and I apologize.

However, I’d like to point out that it’s difficult and costly to implement this strategy correctly and I still maintain that the approach I've been recommending is perfectly viable for most applications.

Jeremy: “Your recommendations will only work well for the people replying to your posts if you are interested in personally supporting their products when deployed in the field.”

Given the choice between an application that abuses catch (Exception) and another which catches only the exceptions that it can handle gracefully, I'd choose to support the second application in a heart-beat.

Jeremy: “Their customers and partners don't care about what FxCop might have recommended to the developer.”

Not directly, but they do care about software quality, reliability, and overall correctness. Let’s take two familiar examples: Microsoft Excel and the C# compiler. I don’t want Excel to crash, but it would be much worse if it ever produced an incorrect value in a spreadsheet that I use to manage my personal finances. Similarly, I prefer to see the compiler ICE (Internal Compiler Error) in favor of emitting bad code. Of course, in an ideal world, Excel would never crash and the compiler would never ICE, but I’ve seen both happen and I’m sure it was in my best interest even if it upset me at the time.

Niall: “I think you have to realise that exception handling is not just for the developer's benefit. The application is there to serve the user, not the developer, so simply bombing out because you can't display a new form is going to require the user to restart the application more than is really required.”

Yes, the application is there to serve the user, not the developer and I couldn’t agree more. In that situation, you have to ask yourself why you couldn’t display the form. If the only reason you can provide is that your catch (Exception) block was hit, then you really have no idea whether it’s in the best interest of the user to continue executing. For example, what if one of your assemblies just failed to load, or you’ve run out of memory, or the root cause is actually a corruption in shared data? What will go wrong next? On the other hand, if you catch (IOException) while trying to read the CSV file that will ultimately be used to populate the new form, then you know beyond a shadow of a doubt that the correct application behavior is to inform the user that the file could not be opened and allow them to continue to use the application which remains in a consistent state.

Niall: “In a previous project I worked on, we had a lot of places where exceptions were caught and error reports were sent back to the dev team. Therefore, the exceptions weren't just disappearing quietly, they were known to the developers.

In many circumstances, the application would then continue. This is because a lot of our handling of exceptions would result in the form the exception came from closing or not appearing. Basically that element of the workflow did not occur. For almost all cases, this left the application in a state that allowed it to continue without problems. Of course, it wasn't 100% perfect. We did have a threshold of a certain number of exception reports in a certain amount of time would cause the handler to exit the app, though.”

Both exception logging and using an exception count threshold are popular approaches for applications which catch all exceptions in places. In fact, this is actually exactly how the current version of FxCop works. Our experience with FxCop’s current exception handling policy has not been positive at all and so I would not suggest this approach universally. Nevertheless, as the application developer, it’s up to you to choose the appropriate policy.

Niall: “Especially when the environment is such that you cannot deploy a fix at a day's notice, having the users restarting the application frequently when you could provide better is basically developing to suit the developers instead of the users.”

If it turns out that your application is crashing “frequently” enough that users have to restart it all the time, then it wasn’t ready to ship in the first place. By the time you’re ready to ship, you should have uncovered nearly all of the exceptions that you need to handle or prevent, and those that remain should be extremely uncommon. Besides careful testing on your end during the development cycle, it’s important to provide regular preview releases for your customers and partners to pound on. During that time, it will be invaluable that exception-related bugs are easy to diagnose and fix quickly. By the time you ship, you will have software which neither crashes nor swallows bugs!

Niall: “Of course, it can make diagnosing problems more difficult, but the role of the software is to make the user's job easier, not the developer's. Sometimes the developer just has to work a bit harder because otherwise the work goes on the user's plate.”

I never meant to imply that ease of diagnosis is an end unto itself. It is a means through which you can deliver better software with fewer defects, which most definitely serves to make the user’s life easier. Indeed, the developer often does have to work harder: uncovering the specific exceptions that need to be handled and the additional code that needs to be in place to prevent the others is often harder than slapping in an additional catch (Exception) block, but it’s the right thing to do…

FAQ: Why does FxCop warn against catch(Exception)? - Part 2 [Nick Guerrera]

nicholg — Sun, 18 Jun 2006 08:04:00 GMT

This is the second installment in a three-part series on why FxCop warns against catch(Exception):
FAQ: Why does FxCop warn against catch(Exception)? - Part 1
FAQ: Why does FxCop warn against catch(Exception)? - Part 2
FAQ: Why does FxCop warn against catch(Exception)? - Part 3

On Wednesday, I explained why catch (Exception) is a bad idea, and many of you replied with interesting comments. Since it was too cumbersome to write everything I had to say in the comments section, I’ve replied to your comments below.

K: “Do you have a list of the 'unchecked' exceptions?”

No. I don’t have a definitive list of the exceptions which should always be prevented and never caught. The best advice I can offer here is to follow the API documentation on a case-by-case basis. Don’t immediately assume that you need catch blocks for each of the exceptions that are listed in the documentation for a particular API. Instead, for each exception, ask you yourself if there’s a simple way to prevent it. If there is, then put in the preventative code and leave out the catch block.

This can be tough to discern in some circumstances. For example, it may seem that a call to File.Exists can prevent FileNotFoundException, but there’s a race condition where the operation will still fail if the file is deleted in between the time File.Exists returns true and the call is initiated. Also, there are some methods in the .NET Framework which misuse exception types. For example, in an ideal world, you should never catch ArgumentException, but Enum.Parse throws it to indicate that the input does not represent one of the enum values. Since there’s no way to prevent that short of rewriting Enum.Parse, you have to consider ArgumentException ‘checked’ in that specific case.

If you’re unsure about a specific API, try asking for help on http://forums.microsoft.com

Gill: “… there is one issue that troubles me: what if my program handles 10 specific exceptions I defined in the same way (when all these exceptions hint at different problems that are related), in this case I would want some catch blocks to perform the same code. If these exceptions don't share a common base, there is no way to make all of them perform the same code short of using the same lines (or method call) in each catch block.”

I don’t think there are that many methods out there which throw 10 unrelated and unpreventable exceptions, but I can relate to your frustration with API which throw unrelated exceptions to indicate related failures. Refactoring the shared handler code in to a helper method is the simplest way to deal with the issue. If you find yourself catching the same set of exceptions from the same method in more than one place, consider refactoring out the entire try/catch/catch/… series in to a helper method of its own.

Gill: “Furthermore, if all developers worked correctly and used this guideline my code might be facing unexpected exceptions from 3rd party code bugs. If this 3rd party isn't available to fix the bug, my program can fail at unexpected times.”

I don’t follow the reasoning here. If you hit a bug in 3^rd party code, then catch (Exception) is just going to make things worse. You should treat this unhandled exception no different from any other. It may turn out that you can work around the problem by using the API differently or adding a catch handler for the specific exception type that was raised if it turns out to be recoverable.

Richard: “Of course, it would help if the Exception class was abstract, and the Framework never threw a general Exception! For example, try calling System.Drawing.ColorTranslator.FromHtml("#aaax")”

Youch! You’re right; it’s absolutely terrible to throw an instance of System.Exception and FxCop warns against that as well. I will do my best to argue for reopening and fixing this bug!

Anonymous: “If my program has a feature to auto-save unsaved work every 10 minutes, and the auto-save procedure (which may use a third-party library) throws an unchecked exception, are you suggesting that the program should simply crash out, because this exception must not be handled?”

Yes, that is in fact exactly what I’m suggesting. A bug is a bug is a bug. It doesn’t matter if it’s in your code or 3^rd party code, catch (Exception) will just make it harder to find and fix. Having an auto-save feature is a great way to mitigate the risk of data loss. However, if the auto-save code itself is buggy, then all bets are off. It’s sort of like discovering that your parachute won’t open…

Jeff: “Well here is my slight problem with this. The best example I can give you as to why you absolutely have [to] Catch(Exception ex) to do this is a bug I reported back in Beta 2 … The Browser Control …”

Chris: “… the WebBrowser control will silently eat the NullReferenceException. I want to know when if my code has a bug, but the WebBrowser hides my bugs.”

That’s awful! I will talk to the owners of the Web browser control about getting this fixed. One of the things that I failed to mention in my original post is that it’s much worse to swallow exceptions in library code than in application code. If you’re developing a reusable library, this rule (like many others in FxCop) is doubly important!

Pop Catalin Sever: “Let the entire application crash? Are you kidding? That's really unacceptable. And btw if you notify the user that something bad has happened in most cases he will help out recover the application or some data. If you just let the application close I think that very likely you're going to be in big trouble.”

Let the application continue to run in an indeterminate state and carelessly corrupt data? Are you kidding? ;)

While I agree that the user should be notified that something has gone wrong, I don’t agree that the application should continue running afterwards. Instead, a friendly dialog should allow the user to send an error report before the application closes. If data loss is a potential issue in your application, then implement an auto-save feature. It’s worth noting that this is exactly the approach that’s used in Microsoft Office.

Beginning in .NET 2.0, you don’t need to implement the crash dialog box yourself. If you let the exception go unhandled, a default dialog box will be displayed that allows the user to send an error report to Microsoft. Note that for Windows Forms applications, you need to call Application.SetUnhandledExceptionMode(UnhandledExceptionMode.ThrowException) to make this work.

If you prefer, you can hook the AppDomain.UnhandledException event and display your own dialog that allows users to send a bug report directly to you.

Jeremy: “Here are another three cases where you absolutely must catch Exception (and at the very least provide for adequate logging, even if you then rethrow):

1. In every method you spin up in a new thread.
2. In every method called arbitrarily on threads you don't control (ie. WebMethods, methods exposed via remoting, delegates passed across remoting, windows service control overrides, etc.)
3. Main

Seeing a pattern here? :)”

It sounds like you got burned by the default exception handling policy for secondary threads in .NET 1.0 and 1.1. Thankfully, the situation is vastly improved in .NET 2.0. See http://msdn2.microsoft.com/en-us/library/ms228965.aspx.

If you can’t move to 2.0 just yet, then a better approach than sprinkling catch (Exception) in all of these places is to hook AppDomain.UnhandledException (and Application.ThreadException for Windows Forms applications). In your handler, you can throw up a dialog like the default dialog in .NET 2.0 and call Environment.Exit afterwards.

FAQ: Why does FxCop warn against catch(Exception)? - Part 1 [Nick Guerrera]

nicholg — Thu, 15 Jun 2006 09:11:00 GMT

This is the first installment in a three-part series on why FxCop warns against catch(Exception):
FAQ: Why does FxCop warn against catch(Exception)? - Part 1
FAQ: Why does FxCop warn against catch(Exception)? - Part 2
FAQ: Why does FxCop warn against catch(Exception)? - Part 3

This question comes up a lot, and I think there’s a lot of confusion and controversy about the rule. Many people seem to think that it’s noisy, annoying, and not worth their time. I find that very unfortunate because following its guidance can really help you build better software. Here’s my attempt to convince the Nay-Sayers that catch(Exception) is almost always a terrible idea.

I’ve heard a lot of arguments against DoNotCatchGeneralExceptionTypes, but they generally boil down to one or both of the following:

“If I call an API which doesn’t document which exceptions it can throw, then I have no choice but to catch all possible exceptions!”
“My application needs to be robust; it can’t crash just because of an exception that I forgot to handle!”

Both arguments are ill-conceived because they presume that you can handle an exception even if you don’t know what failure it represents or how it impacts the code that will execute next. There’s an implicit assumption in both arguments that the mere act of catching an exception is equivalent to handling it appropriately, which simply isn’t true.

For the sake of the discussion to follow, exceptions can be divided in to two general categories:

Those that signal bugs (i.e. API misuse), or catastrophic system failures
(e.g. ArgumentException, NullReferenceException, ExecutionEngineException.)
Those that signal unpreventable yet recoverable error conditions.
(e.g. FileNotFoundException, SocketException.)

In languages like Java, which have a notion of checked exceptions, only exceptions of the second kind are eligible to be checked while exceptions of the first kind must be left unchecked. On that basis and for lack of better terminology, I will hereafter refer to exceptions in the first bucket as ‘unchecked’ and exceptions in the second bucket as ‘checked’. (Note the quotes.) I am using the terms loosely to mean that if exceptions were checked in .NET, then those in the first bucket would remain unchecked while those in the second bucket could become checked.

Independent of where you stand on the checked exception debate, this distinction is very important to hold in your mind when writing exception handling code. In particular, do you really ever want to catch the ‘unchecked’ exceptions at all? Probably not! Instead, you should prevent them from occurring in the first place. For example, check if a variable is null before dereferencing it, don’t catch (NullReferenceException).

If a bug in your code manifests itself as an exception (and most of the ‘unchecked’ exceptions are just that), then it’s best to let the application terminate right at the point of failure. When the bug is discovered, you’ll get exactly the diagnostic information you need to fix it quickly, add the appropriate regression tests, and move on. On the other hand, debugging a system which aggressively swallows general exceptions feels like you’re one of the police investigators in “CSI: Miami”. The culprit has left the crime scene and you have to work backwards from the subtle clues in your program’s incorrect behavior.

And that’s the principal reason to avoid catch (Exception): it hides bugs in your code. These bugs are far more costly to resolve and since they can go undetected, the quality of your software suffers.

Some readers might be thinking that it would be helpful if the .NET Framework exception class hierarchy reflected the ‘checked’ vs. ‘unchecked’ nature of exceptions. In fact, it’s rather seductive to imagine a base class, say System.CheckedException, for all of the ‘checked’ exceptions. The argument follows that you could then replace catch (Exception) with catch (CheckedException)… and the problem would be solved since you no longer catch those insidious ‘unchecked’ exceptions. Unfortunately, this approach would be just as flawed. FxCop would still warn against catch (CheckedException) because it’s still far too general. By definition, ‘checked’ exceptions are unpreventable and must therefore be caught. Nevertheless, catching them is the easy part; the hard part is deciding what to do next, and that decision is purely a function of the specific exception type and it’s meaning in the given context. For example, to recover from FileNotFoundException for your configuration file, you might use a default configuration, and to recover from a SocketException, you might fall back to a local store until the network becomes available again. However, if you don’t know what to do about it, then let it go.

Returning to the first argument against this rule, please don’t get me wrong, I definitely empathize with the need for accurate exception information in API documentation. However, in the absence of such documentation, the safest approach is to treat all API as
“innocent until proven guilty.” Wait until you have hard evidence that a particular exception can be raised before you attempt to handle it.

Also, be sure to test your exception handling code. For example, delete a file out from underneath your application while it’s running and see how it deals with FileNotFoundException. It’s simply not sufficient to write optimistic and untested code, just because the exception is mentioned in the API documentation. I can’t tell you how many times I’ve seen untested catch handlers fail to work as expected. The classic example is a formatting exception raised in the error message that’s never provoked from a test. Spurious and unnecessary catch (Exception) blocks can completely torpedo your code coverage! (Remember: if it’s not tested, it’s broken.)

One important thing to note is that if you follow our advice and catch fewer exceptions, then exceptions will naturally travel further up the call stack. Sometimes they’ll terminate the application, but other times someone further up the call stack will know what to do and your only job is to clean up after yourself in finally blocks as the stack unwinds.

To summarize, here are some important things to consider when dealing with exceptions in managed code:

Do not catch preventable (‘unchecked’) exceptions.
Only catch the specific unpreventable (‘checked’) exceptions that you are certain can be raised and that you know how to handle.
Test your exception handling code.
Use finally blocks liberally for clean-up code to keep your state as consistent as possible in case an exception that you cannot handle needs to be handled further up the stack.

And finally, I’d like to point out that our team has learned this lesson the hard way. There are actually far too many catch (Exception) blocks in FxCop itself and it has caused us a great deal of grief. We’re working on removing them and I’m confident it will help us to deliver better software!

FAQ: Why do some sources recommend extending ApplicationException while FxCop does not? [Michael Fanning, David Kean]

David M. Kean — Thu, 06 Apr 2006 06:21:00 GMT

TypesShouldNotExtendCertainBaseTypes fires on types that derive from ApplicationException and DoNotRaiseReservedExceptionTypes on members that throw ApplicationException. Why?

There are several outdated documents floating around on the web (some orginally published by Microsoft) recommending that application developers extend ApplicationException. However, this guidance was revised several years ago for a couple of reasons:

It deepens the class hierarchy and presents additional complications for consumers writing exception handlers without providing additional value.
It prevents the reuse of existing exception classes defined in the Base Class Library (BCL).

The official Microsoft Design Guidelines, particularly the Catching and Throwing Standard Exception Types section, have only recently been revamped to include this new information. Both Krzysztof Cwalina and Brad Abrams, who own the Framework Design Guidelines at Microsoft, have both blogged on this issue (ApplicationException considered useless and Introducing the .NET Framework Standard Library Annotated Reference).

If you see any MSDN samples or articles that use ApplicationException (or violate any FxCop rule, for that matter), please file a bug on the Microsoft Connect.