KennisbankExamencentrum
NL · NLNederlands (Nederland)
Taal kiezen13

CKTIS / C#

NotNullWhenAttribute — een voorwaardelijke garantie op niet-null

NotNullWhenAttribute beschrijft het verband tussen het bool-resultaat van een methode en de null-status van een argument. Hiermee kan nullable-analyse de veilige tak herkennen na een controlemethode of een methode in Try*-stijl, zonder de !-operator te gebruiken.

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

Syntax

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

NotNullWhenAttribute in de naamruimte System.Diagnostics.CodeAnalysis is een parameterattribuut dat een voorwaardelijke postconditie beschrijft. [NotNullWhen(true)] betekent dat het argument na een normale terugkeer van de methode met true niet null is, ook al staat het type dat toe. De verkorte attribuutnaam is NotNullWhen; de constructor accepteert een bool en de eigenschap ReturnValue geeft die waarde beschikbaar.

Pas het attribuut toe op parameters, waaronder out- en ref-parameters, niet op de retourwaarde. [NotNullWhen(false)] koppelt de garantie aan het resultaat false. Het tegenovergestelde resultaat betekent op zichzelf niet dat het argument null is: het attribuut specificeert de status in die tak niet.

Schakel nullable-analyse in, bijvoorbeeld met #nullable enable. In het voorbeeld garandeert TryGetName een niet-null out-waarde wanneer de methode true retourneert. Daarom heeft name.Length geen !-operator nodig. Het attribuut controleert of wijzigt waarden niet tijdens runtime; de implementatie moet het contract naleven.

De API is beschikbaar in de doelomgeving .NET 10. De repository-instelling LangVersion=preview betekent niet dat dit attribuut een experimentele functie is.

Voorbeelden

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

Resultaat

3
missing

De getoonde code en het opgegeven resultaat zijn in een geïsoleerde omgeving geverifieerd met de methode die in het verificatiebewijs voor exact deze versie is vastgelegd.

Bronnen