CA1512: Use ArgumentOutOfRangeException throw helper

Property	Value
Rule ID	CA1512
Title	Use ArgumentOutOfRangeException throw helper
Category	Maintainability
Fix is breaking or non-breaking	Non-Breaking
Enabled by default in .NET 8	As suggestion

Cause

Code checks whether an argument is less than or greater than a given value and then conditionally throws an ArgumentOutOfRangeException.

Rule description

Argument checks have a substantial impact on code size and often dominate the code for small functions and property setters. These checks prevent inlining and cause substantial instruction-cache pollution. Throw-helper methods such as ArgumentOutOfRangeException.ThrowIfGreaterThan are simpler and more efficient than if blocks that construct a new exception instance.

Example

The following code snippet shows violations of CA1512:

void M(int arg)
{
    if (arg is 0)
        throw new ArgumentOutOfRangeException(nameof(arg));
    if (arg < 0)
        throw new ArgumentOutOfRangeException(nameof(arg));
    if (arg <= 0)
        throw new ArgumentOutOfRangeException(nameof(arg));
    if (arg <= 42)
        throw new ArgumentOutOfRangeException(nameof(arg));
    if (arg < 42)
        throw new ArgumentOutOfRangeException(nameof(arg));
    if (arg > 42)
        throw new ArgumentOutOfRangeException(nameof(arg));
    if (arg >= 42)
        throw new ArgumentOutOfRangeException(nameof(arg));
    if (arg == 42)
        throw new ArgumentOutOfRangeException(nameof(arg));
    if (arg != 42)
        throw new ArgumentOutOfRangeException(nameof(arg));
}

The following code snippet shows the fixes:

void M(int arg)
{
    ArgumentOutOfRangeException.ThrowIfZero(arg);
    ArgumentOutOfRangeException.ThrowIfNegative(arg);
    ArgumentOutOfRangeException.ThrowIfNegativeOrZero(arg);
    ArgumentOutOfRangeException.ThrowIfLessThanOrEqual(arg, 42);
    ArgumentOutOfRangeException.ThrowIfLessThan(arg, 42);
    ArgumentOutOfRangeException.ThrowIfGreaterThan(arg, 42);
    ArgumentOutOfRangeException.ThrowIfGreaterThanOrEqual(arg, 42);
    ArgumentOutOfRangeException.ThrowIfEqual(arg, 42);
    ArgumentOutOfRangeException.ThrowIfNotEqual(arg, 42);
}

How to fix violations

Replace the if block that throws the exception with a call to one of the following throw-helper methods:

• ArgumentOutOfRangeException.ThrowIfZero<T>(T, String)
• ArgumentOutOfRangeException.ThrowIfNegative<T>(T, String)
• ArgumentOutOfRangeException.ThrowIfNegativeOrZero<T>(T, String)
• ArgumentOutOfRangeException.ThrowIfLessThanOrEqual<T>(T, T, String)
• ArgumentOutOfRangeException.ThrowIfLessThan<T>(T, T, String)
• ArgumentOutOfRangeException.ThrowIfGreaterThanOrEqual<T>(T, T, String)
• ArgumentOutOfRangeException.ThrowIfGreaterThan<T>(T, T, String)
• ArgumentOutOfRangeException.ThrowIfEqual<T>(T, T, String)
• ArgumentOutOfRangeException.ThrowIfNotEqual<T>(T, T, String)

Or, in Visual Studio, use the lightbulb menu to fix your code automatically.

When to suppress warnings

It's safe to suppress a violation of this rule if you're not concerned about the maintainability of your code. It is also fine to suppress violations that are identified to be false positives.

Suppress a warning

If you just want to suppress a single violation, add preprocessor directives to your source file to disable and then re-enable the rule.

#pragma warning disable CA1512
// The code that's violating the rule is on this line.
#pragma warning restore CA1512

To disable the rule for a file, folder, or project, set its severity to none in the configuration file.

[*.{cs,vb}]
dotnet_diagnostic.CA1512.severity = none

For more information, see How to suppress code analysis warnings.