Edit

CA2201: Do not raise reserved exception types

  • Article
Property Value
Rule ID CA2201
Title Do not raise reserved exception types
Category Usage
Fix is breaking or non-breaking Breaking
Enabled by default in .NET 8 No

Cause

A method raises an exception type that's too general or that's reserved by the runtime.

Rule description

The following exception types are too general to provide sufficient information to the user:

The following exception types are reserved and should be thrown only by the common language runtime:

Don't throw general exceptions

If you throw a general exception type, such as Exception or SystemException, in a library or framework, it forces consumers to catch all exceptions, including unknown exceptions that they don't know how to handle.

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

Throw specific exceptions

The following table shows which exception to throw for various types of invalid arguments, including the value parameter in the set accessor of a property.

Invalid argument Exception
null reference ArgumentNullException
Outside the allowed range of values (such as an index for a collection or list) ArgumentOutOfRangeException
Invalid enum value InvalidEnumArgumentException
Contains a format that doesn't meet the parameter specifications of a method (such as the format string for ToString(String)) FormatException
Otherwise invalid ArgumentException

The following table shows which exception to throw for various types of invalid operations.

Invalid operation Exception
Operation is invalid for the current state of an object. InvalidOperationException
Operation is performed on an object that has been disposed. ObjectDisposedException
Operation is not supported (such as in an overridden Stream.Write in a stream opened for reading). NotSupportedException
Conversion would result in an overflow (such as in an explicit cast operator overload). OverflowException

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

How to fix violations

To fix a violation of this rule, change the type of the thrown exception to a specific type that's not one of the reserved types.

When to suppress warnings

Do not suppress a warning from this rule.