What exceptions should be thrown for invalid or unexpected parameters in .NET?

Question

What types of exceptions should be thrown for invalid or unexpected parameters in .NET? When would I choose one instead of another?

Follow-up:

Which exception would you use if you have a function expecting an integer corresponding to a month and you passed in '42'? Would this fall into the "out of range" category even though it's not a collection?

Answer 1

I like to use: ArgumentException, ArgumentNullException, and ArgumentOutOfRangeException.

• ArgumentException – Something is wrong with the argument.
• ArgumentNullException – Argument is null.
• ArgumentOutOfRangeException – I don’t use this one much, but a common use is indexing into a collection, and giving an index which is to large.

There are other options, too, that do not focus so much on the argument itself, but rather judge the call as a whole:

• InvalidOperationException – The argument might be OK, but not in the current state of the object. ^{_{Credit goes to STW (previously Yoooder). Vote his answer up as well.}}
• NotSupportedException – The arguments passed in are valid, but just not supported in this implementation. Imagine an FTP client, and you pass a command in that the client doesn’t support.

The trick is to throw the exception that best expresses why the method cannot be called the way it is. Ideally, the exception should be detailed about what went wrong, why it is wrong, and how to fix it.

I love when error messages point to help, documentation, or other resources. For example, Microsoft did a good first step with their KB articles, e.g. “Why do I receive an "Operation aborted" error message when I visit a Web page in Internet Explorer?”. When you encounter the error, they point you to the KB article in the error message. What they don’t do well is that they don’t tell you, why specifically it failed.

^{_{Thanks to STW (ex Yoooder) again for the comments.}}

---

In response to your followup, I would throw an ArgumentOutOfRangeException. Look at what MSDN says about this exception:

ArgumentOutOfRangeException is thrown when a method is invoked and at least one of the arguments passed to the method is not null reference (Nothing in Visual Basic) and does not contain a valid value.

So, in this case, you are passing a value, but that is not a valid value, since your range is 1–12. However, the way you document it makes it clear, what your API throws. Because although I might say ArgumentOutOfRangeException, another developer might say ArgumentException. Make it easy and document the behavior.