WissensdatenbankPrüfungszentrum
DEDeutsch
Sprache wählen13

CKTIS / C#

NotNullWhenAttribute — eine bedingte Nicht-null-Garantie

NotNullWhenAttribute beschreibt den Zusammenhang zwischen dem booleschen Ergebnis einer Methode und dem Nullzustand eines Arguments. So kann die Nullable-Analyse nach einer prüfenden Methode oder einer Methode im Try*-Stil den sicheren Zweig erkennen, ohne den !-Operator zu verwenden.

Version: .NET 10; repository net10.0 and LangVersion=preview; feature versions require per-entry verification

Syntax

bool Method([NotNullWhen(true)] string? value)
bool TryMethod([NotNullWhen(true)] out string? value)
bool IsMissing([NotNullWhen(false)] string? value)

NotNullWhenAttribute im Namespace System.Diagnostics.CodeAnalysis ist ein Parameterattribut, das eine bedingte Nachbedingung beschreibt. [NotNullWhen(true)] bedeutet, dass das Argument nach der normalen Rückkehr der Methode mit true nicht null ist, obwohl sein Typ null zulässt. Der Kurzname des Attributs lautet NotNullWhen; sein Konstruktor erwartet einen bool, und die Eigenschaft ReturnValue stellt diesen Wert bereit.

Das Attribut wird auf Parameter angewendet, einschließlich out- und ref-Parametern, nicht auf den Rückgabewert. [NotNullWhen(false)] verknüpft die Garantie mit dem Ergebnis false. Das jeweils andere Ergebnis bedeutet nicht automatisch, dass das Argument null ist: Das Attribut legt seinen Zustand in diesem Zweig nicht fest.

Aktivieren Sie die Nullable-Analyse, zum Beispiel mit #nullable enable. Im Beispiel garantiert TryGetName bei Rückgabe von true einen Nicht-null-Wert für den out-Parameter, sodass name.Length keinen !-Operator benötigt. Das Attribut prüft Werte zur Laufzeit weder selbst noch ändert es sie; die Implementierung muss den Vertrag einhalten.

Die API ist in der Zielumgebung .NET 10 verfügbar. Die Repository-Einstellung LangVersion=preview bedeutet nicht, dass dieses Attribut ein experimentelles Feature ist.

Beispiele

#nullable enable
using System;
using System.Diagnostics.CodeAnalysis;

internal static class Program
{
    private static bool TryGetName(int id, [NotNullWhen(true)] out string? name)
    {
        name = id == 1 ? "Ada" : null;
        return name is not null;
    }

    private static void Main()
    {
        foreach (int id in new[] { 1, 2 })
        {
            if (TryGetName(id, out string? name))
                Console.WriteLine(name.Length);
            else
                Console.WriteLine("missing");
        }
    }
}

Ergebnis

3
missing

Der angezeigte Code und das angegebene Ergebnis wurden in einer isolierten Umgebung mit der im Prüfnachweis für genau diese Version dokumentierten Methode verifiziert.

Quellen