Znalostní bázeCentrum zkoušek
CSČeština
Vybrat jazyk13

CKTIS / C#

NotNullWhenAttribute — podmíněná záruka nenulové hodnoty

NotNullWhenAttribute popisuje vztah mezi bool výsledkem metody a stavem null jejího argumentu. Analýze nullable umožňuje rozpoznat bezpečnou větev po kontrolní metodě nebo metodě ve stylu Try*, aniž by bylo nutné použít operátor !.

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

Syntaxe

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

NotNullWhenAttribute v oboru názvů System.Diagnostics.CodeAnalysis je atribut parametru, který popisuje podmíněnou následnou podmínku. [NotNullWhen(true)] znamená, že po běžném návratu metody s výsledkem true není argument null, přestože to jeho typ připouští. Zkrácený název atributu je NotNullWhen; jeho konstruktor přijímá bool a vlastnost ReturnValue tuto hodnotu zpřístupňuje.

Atribut použijte u parametrů, včetně parametrů out a ref, nikoli u návratové hodnoty. [NotNullWhen(false)] váže záruku na výsledek false. Opačný výsledek sám o sobě neznamená, že argument je null: atribut jeho stav v této větvi neurčuje.

Povolte analýzu nullable, například pomocí #nullable enable. V příkladu metoda TryGetName zaručuje nenulovou hodnotu parametru out, když vrátí true, takže name.Length nevyžaduje operátor !. Atribut za běhu hodnoty nekontroluje ani nemění; implementace musí smlouvu dodržet.

Rozhraní API je dostupné v cílovém prostředí .NET 10. Nastavení repozitáře LangVersion=preview neznamená, že je tento atribut experimentální funkcí.

Příklady

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

Výsledek

3
missing

Zobrazený kód a uvedený výsledek byly ověřeny v izolovaném prostředí metodou zaznamenanou v dokladu o ověření této přesné verze.

Zdroje