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.