Odkazové typy s možnou hodnotou null (referenční dokumentace jazyka C#)

Poznámka:

Tento článek popisuje odkazové typy s možnou hodnotou null. Můžete také deklarovat typy hodnot s možnou hodnotou null.

V kódu, který je v kontextu s možnou hodnotou null, můžete použít odkazové typy s možnou hodnotou null. Odkazové typy s možnou hodnotou null, upozornění statické analýzy null a operátor null-forgiving jsou volitelné jazykové funkce. Ve výchozím nastavení jsou všechny vypnuté. Kontext s možnou hodnotou null můžete řídit na úrovni projektu pomocí nastavení sestavení nebo kódu pomocí pragmas.

Referenční dokumentace jazyka C# dokumentuje naposledy vydané verze jazyka C#. Obsahuje také počáteční dokumentaci k funkcím ve verzi Public Preview pro nadcházející jazykovou verzi.

Dokumentace identifikuje všechny funkce, které byly poprvé představeny v posledních třech verzích jazyka nebo v aktuálních verzích Public Preview.

Návod

Informace o tom, kdy byla funkce poprvé představena v jazyce C#, najdete v článku o historii verzí jazyka C#.

Důležité

Všechny šablony projektu umožňují kontextu s možnou hodnotou null projektu. Projekty vytvořené pomocí dřívějších šablon tento prvek nezahrnují a tyto funkce jsou vypnuté, pokud je v souboru projektu nepovolíte nebo nepoužijete pragmas.

V kontextu s možnou hodnotou null:

• Je nutné inicializovat proměnnou typu odkazu T s hodnotou, která není null, a nikdy nemůžete přiřadit hodnotu, která by mohla být null.
• Proměnnou typu odkazu T? můžete inicializovat pomocí null nebo přiřadit null, ale před dereferencováním ji musíte zkontrolovat null .
• Pokud použijete operátor null-progiving na proměnnou m typu T?, jako v m!, proměnná se považuje za nenulovou.

Kompilátor vynucuje rozdíly mezi nenulovým odkazovým typem T a typem T? odkazu s možnou hodnotou null pomocí předchozích pravidel. Proměnná typu T a proměnná typu T? jsou stejného typu .NET. Následující příklad deklaruje nenulový řetězec a řetězec s možnou hodnotou null a potom pomocí operátoru null-forgiving přiřadí hodnotu k řetězci, který není nullable:

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

Proměnné notNull i nullable oba používají String typ. Vzhledem k tomu, že typy s možnou hodnotou null a s možnou hodnotou null používají stejný typ, nemůžete použít odkaz s možnou hodnotou null v několika umístěních. Obecně nelze použít odkazový typ s možnou hodnotou null jako základní třídu nebo implementované rozhraní. V žádném objektovém vytvoření nebo testovacím výrazu typu nelze použít odkaz s možnou hodnotou null. Jako typ přístupového výrazu člena nemůžete použít odkaz s možnou hodnotou null. Následující příklady ukazují tyto konstrukce:

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

Odkazy s možnou hodnotou null a statická analýza

Příklady v předchozí části ilustrují povahu referenčních typů s možnou hodnotou null. Odkazové typy s možnou hodnotou null nejsou nové typy tříd, ale spíše poznámky k existujícím typům odkazů. Kompilátor tyto poznámky používá k nalezení potenciálních chyb odkazu null ve vašem kódu. Neexistuje žádný rozdíl mezi nenulovým odkazovým typem a typem odkazu s možnou hodnotou null. Kompilátor nepřidá žádnou kontrolu za běhu pro nenulové odkazové typy. Výhody jsou v analýze doby kompilace. Kompilátor generuje upozornění, která vám pomůžou najít a opravit potenciální chyby null v kódu. Deklarujete svůj záměr a kompilátor vás upozorní, když váš kód tento záměr porušuje.

Důležité

Poznámky odkazu s možnou hodnotou null nezavádějí změny chování, ale jiné knihovny můžou použít reflexi k vytvoření jiného chování modulu runtime pro odkazové typy s možnou hodnotou null a nenulovou. Entity Framework Core zejména čte atributy s možnou hodnotou null. Interpretuje odkaz s možnou hodnotou null jako volitelnou hodnotu a nenulový odkaz jako požadovanou hodnotu.

V kontextu s povolenou hodnotou null kompilátor provádí statickou analýzu proměnných libovolného typu odkazu, a to jak s možnou hodnotou null, tak bez hodnoty null. Kompilátor sleduje stav null každé referenční proměnné jako buď not-null , nebo možná-null. Výchozí stav odkazu bez hodnoty null není null. Výchozí stav odkazu s možnou hodnotou null je možná null.

Odkazové typy bez null by vždy měly být bezpečné pro dereference, protože jejich stav null není null. Pokud chcete toto pravidlo vynutit, kompilátor vydá upozornění, pokud není typ odkazu s možnou hodnotou null inicializován na hodnotu, která není null. Musíte přiřadit místní proměnné, kde je deklarujete. Každé pole musí mít přiřazenou hodnotu not-null v inicializátoru pole nebo každém konstruktoru. Kompilátor vydává upozornění, když je odkaz s možnou hodnotou null přiřazený k odkazu, jehož stav je možná null. Obecně platí, že nenulový odkaz není null a při dereferenci těchto proměnných se nevystavují žádná upozornění.

Poznámka:

Pokud přiřadíte výraz s možnou hodnotou null k nenulovatelnému typu odkazu, kompilátor vygeneruje upozornění. Kompilátor pak vygeneruje upozornění pro danou proměnnou, dokud není přiřazený k výrazu not-null .

Můžete inicializovat nebo přiřadit k referenčním typům s možnou hodnotou null null. Proto statická analýza musí před dereferencem určit, že proměnná nemá hodnotu null . Pokud je odkaz s možnou hodnotou null určen jako null, přiřaďte ho proměnné odkazu, která není nullable, vygeneruje upozornění kompilátoru. Následující třída ukazuje příklady těchto upozornění:

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;
    }
}

Následující fragment kódu ukazuje, kde kompilátor generuje upozornění při použití této třídy:

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.");

Předchozí příklady ukazují, jak statická analýza kompilátoru určuje stav null referenčních proměnných. Kompilátor používá pravidla jazyka pro kontroly a přiřazení null, aby informoval svou analýzu. Kompilátor nemůže předpokládat sémantiku metod nebo vlastností. Pokud voláte metody, které provádějí kontroly null, kompilátor nemůže tyto metody znát vliv na stav null proměnné. Do rozhraní API můžete přidat atributy, které kompilátoru informují o sémantice argumentů a návratových hodnotách. Mnoho běžných rozhraní API v knihovnách .NET má tyto atributy. Kompilátor například správně interpretuje IsNullOrEmpty jako kontrolu null. Další informace o atributech, které platí pro statickou analýzu stavu null, najdete v článku o atributech s možnou hodnotou Null.

Nastavení kontextu s možnou hodnotou null

Kontext s možnou hodnotou null můžete řídit dvěma způsoby. Na úrovni projektu přidejte <Nullable>enable</Nullable> nastavení projektu. Do jednoho zdrojového souboru jazyka C# přidejte direktivu #nullable enable pragma, která povolí kontext s možnou hodnotou null. Přečtěte si článek o nastavení strategie s možnou hodnotou null. Před .NET 6 používají nové projekty výchozí <Nullable>disable</Nullable>. Počínaje rozhraním .NET 6 zahrnují <Nullable>enable</Nullable> nové projekty prvek v souboru projektu.

specifikace jazyka C#

Další informace naleznete v části Typy odkazů s možnou hodnotou Nullspecifikace jazyka C#.

Viz také

• Typy hodnot s možnou hodnotou null