CA1512: Verwenden Sie ArgumentOutOfRangeException throw-Hilfsprogramm

Eigenschaft	Wert
Regel-ID	CA1512
Titel	Verwenden von ArgumentOutOfRangeException throw-Hilfsprogramm
Kategorie	Wartbarkeit
Fix führt oder führt nicht zur Unterbrechung	Nicht unterbrechend
Standardmäßig in .NET 8 aktiviert	Als Vorschlag

Ursache

Der Code überprüft, ob ein Argument kleiner oder größer als ein bestimmter Wert ist, und löst dann bedingt ein ArgumentOutOfRangeException aus.

Regelbeschreibung

Argumentprüfungen wirken sich erheblich auf die Codegröße aus und beherrschen häufig den Code für kleine Funktionen und Eigenschaftssetter. Diese Überprüfungen verhindern das Einfügen und verursachen eine erhebliche Belastung des Befehlszwischenspeichers. Throw-Hilfsmethoden wie ArgumentOutOfRangeException.ThrowIfGreaterThan sind einfacher und effizienter als if-Blöcke, die eine neue Ausnahmeinstanz erstellen.

Beispiel

Der folgende Codeausschnitt zeigt zwei Verstöße gegen 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));
}

Der folgende Codeausschnitt zeigt die Korrekturen:

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);
}

Behandeln von Verstößen

Ersetzen Sie den if-Block, der die Ausnahme auslöst, durch einen Aufruf einer der folgenden Throw-Hilfsmethoden:

• 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)

Oder verwenden Sie in Visual Studio das Glühbirnenmenü, um Ihren Code automatisch zu korrigieren.

Wann sollten Warnungen unterdrückt werden?

Es ist sicher, einen Verstoß gegen diese Regel zu unterdrücken, wenn Sie sich keine Gedanken über die Wartbarkeit Ihres Codes machen. Es ist auch in Ordnung, Verstöße zu unterdrücken, die als falsch positive Ergebnisse identifiziert werden.

Unterdrücken einer Warnung

Um nur eine einzelne Verletzung zu unterdrücken, fügen Sie der Quelldatei Präprozessoranweisungen hinzu, um die Regel zu deaktivieren und dann wieder zu aktivieren.

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

Um die Regel für eine Datei, einen Ordner oder ein Projekt zu deaktivieren, legen Sie den Schweregrad in der Konfigurationsdatei auf none fest.

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

Weitere Informationen finden Sie unter Vorgehensweise: Unterdrücken von Codeanalyse-Warnungen.