Null-verwijzingstypen (C#-verwijzing)

U kunt null-referentietypen gebruiken in code die zich in een context met null-compatibele waarden bevindt. Null-referentietypen, de waarschuwingen voor statische analyse null en de operator null-forgiving zijn optionele taalfuncties. Alles is standaard uitgeschakeld. U bepaalt een null-context op projectniveau met behulp van build-instellingen of in code met behulp van pragma's.

De C#-taalreferentiedocumenten de laatst uitgebrachte versie van de C#-taal. Het bevat ook de eerste documentatie voor functies in openbare previews voor de aanstaande taalrelease.

De documentatie identificeert alle functies die voor het eerst zijn geïntroduceerd in de laatste drie versies van de taal of in de huidige openbare previews.

In een niet-compatibele context:

• U moet een variabele van een verwijzingstype T initialiseren met een niet-null-waarde en u kunt nooit een waarde toewijzen die kan zijn null.
• U kunt een variabele van een verwijzingstype T? initialiseren met null of toewijzen null, maar u moet deze null controleren voordat u deductie ongedaan maakt.
• Wanneer u de operator null-forgiving toepast op een variabele m van het type T?, zoals in m!, wordt de variabele beschouwd als niet-null.

De compiler dwingt het onderscheid af tussen een niet-nullable verwijzingstype T en een null-verwijzingstype T? met behulp van de voorgaande regels. Een variabele van het type T en een variabele van het type T? zijn hetzelfde .NET-type. In het volgende voorbeeld worden een niet-null-tekenreeks en een null-tekenreeks declareerd en wordt vervolgens de operator null-forgiving gebruikt om een waarde toe te wijzen aan een niet-null-tekenreeks:

string notNull = "Hello";
string? nullable = default;
notNull = nullable!; // null forgiveness

De variabelen notNull en nullable beide gebruiken het String type. Omdat de niet-nullbare en null-bare typen beide hetzelfde type gebruiken, kunt u geen null-verwijzingstype op verschillende locaties gebruiken. Over het algemeen kunt u geen null-verwijzingstype gebruiken als basisklasse of geïmplementeerde interface. U kunt geen null-verwijzingstype gebruiken in een expressie voor het maken van objecten of het testen van typen. U kunt geen null-verwijzingstype gebruiken als het type lidtoegangsexpressie. In de volgende voorbeelden ziet u de volgende constructies:

public MyClass : System.Object? // not allowed
{
}

var nullEmpty = System.String?.Empty; // Not allowed
var maybeObject = new object?(); // Not allowed
try
{
    if (thing is string? nullableString) // not allowed
        Console.WriteLine(nullableString);
} catch (Exception? e) // Not Allowed
{
    Console.WriteLine("error");
}

Null-verwijzingen en statische analyse

In de voorbeelden in de vorige sectie ziet u de aard van null-verwijzingstypen. Null-verwijzingstypen zijn geen nieuwe klassetypen, maar eerder aantekeningen op bestaande referentietypen. De compiler gebruikt deze aantekeningen om potentiële null-verwijzingsfouten in uw code te vinden. Er is geen runtime-verschil tussen een niet-null-verwijzingstype en een null-verwijzingstype. De compiler voegt geen runtimecontrole toe voor niet-nullable referentietypen. De voordelen zijn opgenomen in de analyse van de compilatietijd. De compiler genereert waarschuwingen waarmee u potentiële null-fouten in uw code kunt vinden en oplossen. U declareert uw intentie en de compiler waarschuwt u wanneer uw code die intentie schendt.

In een context met null-functionaliteit voert de compiler statische analyse uit op variabelen van elk verwijzingstype, zowel nullable als niet-nullable. De compiler houdt de null-status van elke verwijzingsvariabele bij als niet-null of misschien-null. De standaardstatus van een niet-null-verwijzing is niet null. De standaardstatus van een null-verwijzing is misschien null.

Niet-null-referentietypen moeten altijd veilig zijn om te deductie omdat de null-status niet null is. Om deze regel af te dwingen, geeft de compiler waarschuwingen uit als een niet-nullable verwijzingstype niet is geïnitialiseerd op een niet-null-waarde. U moet lokale variabelen toewijzen waar u ze declareert. Aan elk veld moet een niet-null-waarde worden toegewezen, in een veld-initialisatiefunctie of elke constructor. De compiler geeft waarschuwingen wanneer een niet-null-verwijzing wordt toegewezen aan een verwijzing waarvan de status mogelijk null is. Over het algemeen is een niet-null-verwijzing niet null en worden er geen waarschuwingen gegeven wanneer u deze variabelen deducteert.

U kunt nullable-verwijzingstypen initialiseren of toewijzen null . Statische analyse moet daarom bepalen dat een variabele niet null is voordat deze wordt gededucteerd. Als wordt vastgesteld dat een null-verwijzing mogelijk null is, genereert het toewijzen ervan aan een niet-null-referentievariabele een compilerwaarschuwing. In de volgende klasse ziet u voorbeelden van deze waarschuwingen:

public class ProductDescription
{
    private string shortDescription;
    private string? detailedDescription;

    public ProductDescription() // Warning! shortDescription not initialized.
    {
    }

    public ProductDescription(string productDescription) =>
        this.shortDescription = productDescription;

    public void SetDescriptions(string productDescription, string? details=null)
    {
        shortDescription = productDescription;
        detailedDescription = details;
    }

    public string GetDescription()
    {
        if (detailedDescription.Length == 0) // Warning! dereference possible null
        {
            return shortDescription;
        }
        else
        {
            return $"{shortDescription}\n{detailedDescription}";
        }
    }

    public string FullDescription()
    {
        if (detailedDescription == null)
        {
            return shortDescription;
        }
        else if (detailedDescription.Length > 0) // OK, detailedDescription can't be null.
        {
            return $"{shortDescription}\n{detailedDescription}";
        }
        return shortDescription;
    }
}

In het volgende codefragment ziet u waar de compiler waarschuwingen verzendt bij het gebruik van deze klasse:

string shortDescription = default; // Warning! non-nullable set to null;
var product = new ProductDescription(shortDescription); // Warning! static analysis knows shortDescription maybe null.

string description = "widget";
var item = new ProductDescription(description);

item.SetDescriptions(description, "These widgets will do everything.");

In de voorgaande voorbeelden ziet u hoe de statische analyse van de compiler de null-status van referentievariabelen bepaalt. De compiler past taalregels toe voor null-controles en -toewijzingen om de analyse ervan te informeren. De compiler kan geen veronderstellingen maken over de semantiek van methoden of eigenschappen. Als u methoden aanroept die null-controles uitvoeren, kan de compiler deze methoden niet kennen van invloed zijn op de null-status van een variabele. U kunt kenmerken toevoegen aan uw API's om de compiler te informeren over de semantiek van argumenten en retourwaarden. Veel algemene API's in de .NET-bibliotheken hebben deze kenmerken. De compiler interpreteert IsNullOrEmpty bijvoorbeeld correct als een null-controle. Zie het artikel over null-able kenmerken voor meer informatie over de kenmerken die van toepassing zijn op statische analyse met null-status.

De null-context instellen

U kunt de context waarop null kan worden uitgevoerd op twee manieren beheren. Voeg op projectniveau de <Nullable>enable</Nullable> projectinstelling toe. Voeg in één C#-bronbestand de #nullable enable pragma toe om de null-context in te schakelen. Zie het artikel over het instellen van een null-strategie. Voordat .NET 6, gebruiken nieuwe projecten de standaardinstelling, <Nullable>disable</Nullable>. Vanaf .NET 6 bevatten nieuwe projecten het <Nullable>enable</Nullable> element in het projectbestand.

C#-taalspecificatie

Zie de sectie Nullable reference types van de C#-taalspecificatie voor meer informatie.

Zie ook

• Typen null-waarden