Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / C#

NotNullWhenAttribute — uma garantia condicional de não nulidade

NotNullWhenAttribute descreve a relação entre o resultado bool de um método e o estado null de um argumento. Permite que a análise nullable reconheça o ramo seguro após um método de verificação ou ao estilo Try*, sem utilizar o operador !.

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

Sintaxe

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

NotNullWhenAttribute, no espaço de nomes System.Diagnostics.CodeAnalysis, é um atributo de parâmetro que descreve uma pós-condição condicional. [NotNullWhen(true)] significa que, após o método terminar normalmente com true, o argumento não é null, embora o respetivo tipo o permita. O nome abreviado do atributo é NotNullWhen; o construtor aceita um bool e a propriedade ReturnValue expõe esse valor.

Aplique o atributo aos parâmetros, incluindo os parâmetros out e ref, e não ao valor devolvido. [NotNullWhen(false)] associa a garantia ao resultado false. O resultado oposto não significa, por si só, que o argumento seja null: o atributo não especifica o respetivo estado nesse ramo.

Ative a análise nullable, por exemplo, com #nullable enable. No exemplo, TryGetName garante um valor out não null quando devolve true, pelo que name.Length não precisa do operador !. O atributo não verifica nem altera valores durante a execução; a implementação tem de respeitar o contrato.

A API está disponível no ambiente de destino .NET 10. A definição do repositório LangVersion=preview não significa que este atributo seja uma funcionalidade experimental.

Exemplos

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

Resultado

3
missing

O código apresentado e o resultado declarado foram verificados num ambiente isolado pelo método registado na prova de verificação desta versão exata.

Fontes