Base de connaissancesCentre d’examen
FRFrançais
Choisir la langue13

CKTIS / C#

NotNullWhenAttribute — une garantie conditionnelle de non-nullité

NotNullWhenAttribute décrit le lien entre le résultat booléen d’une méthode et l’état null d’un argument. Il permet à l’analyse nullable de reconnaître la branche sûre après une méthode de vérification ou une méthode de style Try*, sans utiliser l’opérateur !.

Version : .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, dans l’espace de noms System.Diagnostics.CodeAnalysis, est un attribut de paramètre qui décrit une postcondition conditionnelle. [NotNullWhen(true)] signifie qu’après le retour normal de la méthode avec true, l’argument n’est pas null, même si son type l’autorise. Le nom abrégé de l’attribut est NotNullWhen ; son constructeur accepte un bool, et sa propriété ReturnValue expose cette valeur.

Appliquez l’attribut aux paramètres, y compris ceux marqués out et ref, et non à la valeur de retour. [NotNullWhen(false)] associe la garantie au résultat false. Le résultat opposé ne signifie pas à lui seul que l’argument est null : l’attribut ne précise pas son état dans cette branche.

Activez l’analyse nullable, par exemple avec #nullable enable. Dans l’exemple, TryGetName garantit une valeur out non null lorsqu’elle renvoie true, donc name.Length ne nécessite pas l’opérateur !. L’attribut ne vérifie pas les valeurs à l’exécution et ne les modifie pas ; l’implémentation doit respecter le contrat.

L’API est disponible dans l’environnement cible .NET 10. Le paramètre du dépôt LangVersion=preview ne signifie pas que cet attribut est une fonctionnalité expérimentale.

Exemples

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

Résultat

3
missing

Le code affiché et le résultat déclaré ont été vérifiés dans un environnement isolé selon la méthode consignée dans la preuve de vérification de cette version exacte.

Sources