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.