CA2012: Verwenden Sie ValueTasks ordnungsgemäß.

Eigenschaft	Wert
Regel-ID	CA2012
Titel	Verwenden Sie ValueTasks ordnungsgemäß.
Kategorie	Zuverlässigkeit
Fix führt oder führt nicht zur Unterbrechung	Nicht unterbrechend
Standardmäßig in .NET 10 aktiviert	Als Vorschlag

Ursache

Eine ValueTask-Instanz, die von einem Member-Aufruf zurückgegeben wird, wird auf eine Weise verwendet, die zu Ausnahmen, Beschädigungen oder einer schlechten Leistung führen kann.

Regelbeschreibung

ValueTask-Istanzen, die von Member-Aufrufen zurückgegeben werden, müssen direkt erwartet werden. Alle Versuche, einen ValueTask mehrmals zu verwenden oder direkt auf ein Ergebnis zuzugreifen, bevor es als abgeschlossen bezeichnet wird, können zu einer Ausnahme oder Beschädigung führen. Das Ignorieren eines solchen ValueTask ist wahrscheinlich ein Hinweis auf einen Funktionsfehler und kann die Leistung beeinträchtigen.

Behandeln von Verstößen

Im Allgemeinen müssen ValueTasks direkt erwartet werden, anstatt verworfen oder an anderen Speicherorten wie lokalen Variablen oder Feldern gespeichert zu werden.

Wann sollten Warnungen unterdrückt werden?

Für ValueTask-Objekte, die von beliebigen Memberaufrufen zurückgegeben werden, muss der Aufrufer davon ausgehen, dass der ValueTask nur einmal (z. B. erwartet) verarbeitet werden muss. Wenn Entwickler*innen jedoch auch den aufgerufenen Member steuern und umfassende Kenntnisse über die Implementierung haben, wissen sie möglicherweise, dass es sicher ist, die Warnung zu unterdrücken, z. B. wenn der zurückgegebene ValueTask immer ein Task-Objekt umschließt.

Example

public class NumberValueTask
{
    public async ValueTask<int> GetNumberAsync()
    {
        await Task.Delay(100);
        return 123;
    }

    public async Task UseValueTaskIncorrectlyAsync()
    {
        // This code violates the rule,
        // because ValueTask is awaited multiple times
        ValueTask<int> numberValueTask = GetNumberAsync();

        int first = await numberValueTask;
        int second = await numberValueTask; // <- illegal reuse

        // ...
    }

    // This code satisfies the rule.
    public async Task UseValueTaskCorrectlyAsync()
    {
        int first = await GetNumberAsync();
        int second = await GetNumberAsync();

        // ..
    }

    public async Task UseValueTaskAsTaskAsync()
    {
        ValueTask<int> numberValueTask = GetNumberAsync();

        Task<int> numberTask = numberValueTask.AsTask();

        int first = await numberTask;
        int second = await numberTask;

        // ...
    }
}

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 CA2012
// The code that's violating the rule is on this line.
#pragma warning restore CA2012

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

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

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

Siehe auch

• Zuverlässigkeitsregeln