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:
- System.AccessViolationException
- System.ExecutionEngineException
- System.IndexOutOfRangeException
- System.NullReferenceException
- System.OutOfMemoryException
- System.Runtime.InteropServices.COMException
- System.Runtime.InteropServices.ExternalException
- System.Runtime.InteropServices.SEHException
- System.StackOverflowException
Don't throw general exceptions
If you throw a general exception type, such as System.Exception or System.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 System.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 |
System.ArgumentNullException |
| Outside the allowed range of values (such as an index for a collection or list) | System.ArgumentOutOfRangeException |
Invalid enum value |
System.ComponentModel.InvalidEnumArgumentException |
Contains a format that doesn't meet the parameter specifications of a method (such as the format string for ToString(String)) |
System.FormatException |
| Otherwise invalid | System.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. | System.InvalidOperationException |
| Operation is performed on an object that has been disposed. | System.ObjectDisposedException |
Operation is not supported (such as in an overridden Stream.Write in a stream opened for reading). |
System.NotSupportedException |
| Conversion would result in an overflow (such as in an explicit cast operator overload). | System.OverflowException |
For all other situations, consider creating your own type that derives from System.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.
Example
// This code violates the rule.
throw new Exception();
throw new NullReferenceException();
throw new IndexOutOfRangeException();
// ...
// This code satisfies the rule.
throw new ArgumentException();
throw new ArgumentNullException();
throw new InvalidOperationException();
// ...
// A minimal implementation of inheritance from Exception
public class CustomException : Exception { }
// Or create your own type that derives from Exception
// This code satisfies the rule too.
throw new CustomException();When to suppress warnings
Do not suppress a warning from this rule.