Baza wiedzyCentrum egzaminacyjne
PLPolski
Wybierz język13

CKTIS / C#

NotNullWhenAttribute — warunkowa gwarancja wartości różnej od null

NotNullWhenAttribute opisuje zależność między wynikiem bool metody a stanem null jej argumentu. Umożliwia analizie nullable rozpoznanie bezpiecznej gałęzi po wywołaniu metody sprawdzającej lub metody w stylu Try*, bez używania operatora !.

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

Składnia

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

NotNullWhenAttribute z przestrzeni System.Diagnostics.CodeAnalysis to atrybut parametru opisujący warunkowy warunek końcowy. Zapis [NotNullWhen(true)] oznacza, że po normalnym powrocie metody z wynikiem true argument nie jest null, mimo że jego typ na to pozwala. Skrócona nazwa atrybutu to NotNullWhen; konstruktor przyjmuje bool, a właściwość ReturnValue udostępnia tę wartość.

Atrybut stosuje się do parametrów, również out i ref, a nie do wartości zwracanej. [NotNullWhen(false)] przenosi gwarancję na wynik false. Przeciwny wynik sam w sobie nie oznacza, że argument jest null: atrybut nie określa jego stanu w tej gałęzi.

Włącz analizę nullable, na przykład przez #nullable enable. W przykładzie TryGetName gwarantuje niepusty w sensie null wynik out, gdy zwraca true, dlatego name.Length nie wymaga operatora !. Sam atrybut nie sprawdza wartości podczas wykonania ani ich nie zmienia; implementacja musi dotrzymywać kontraktu.

API jest dostępne w docelowym środowisku .NET 10. Ustawienie repozytorium LangVersion=preview nie oznacza, że ten atrybut jest funkcją eksperymentalną.

Przykłady

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

Wynik

3
missing

Wyświetlony kod i zadeklarowany wynik zweryfikowano w odizolowanym środowisku metodą zapisaną w dowodzie weryfikacji tej dokładnej wersji.

Źródła