Base di conoscenzaCentro esami
ITItaliano
Scegli la lingua13

CKTIS / C#

NotNullWhenAttribute — una garanzia condizionale di non nullità

NotNullWhenAttribute descrive il rapporto tra il risultato bool di un metodo e lo stato null di un argomento. Permette all’analisi nullable di riconoscere il ramo sicuro dopo un metodo di verifica o in stile Try*, senza usare l’operatore !.

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

Sintassi

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

NotNullWhenAttribute, nello spazio dei nomi System.Diagnostics.CodeAnalysis, è un attributo di parametro che descrive una postcondizione condizionale. [NotNullWhen(true)] significa che, dopo il normale ritorno del metodo con true, l’argomento non è null, anche se il tipo lo consente. Il nome abbreviato dell’attributo è NotNullWhen; il costruttore accetta un bool e la proprietà ReturnValue espone tale valore.

Applicare l’attributo ai parametri, compresi quelli out e ref, non al valore restituito. [NotNullWhen(false)] associa la garanzia al risultato false. Il risultato opposto non significa di per sé che l’argomento sia null: l’attributo non ne specifica lo stato in quel ramo.

Abilitare l’analisi nullable, ad esempio con #nullable enable. Nell’esempio, TryGetName garantisce un valore out non null quando restituisce true, quindi name.Length non richiede l’operatore !. L’attributo non verifica i valori durante l’esecuzione e non li modifica; l’implementazione deve rispettare il contratto.

L’API è disponibile nell’ambiente di destinazione .NET 10. L’impostazione del repository LangVersion=preview non significa che questo attributo sia una funzionalità sperimentale.

Esempi

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

Risultato

3
missing

Il codice mostrato e il risultato dichiarato sono stati verificati in un ambiente isolato con il metodo registrato nella prova di verifica di questa versione esatta.

Fonti