Nullwerte zulassende VerweistypenNullable reference types

Mit den in C# 8.0 eingeführten Nullable-Verweistypen und Nicht-Nullable-Verweistypen können Sie wichtige Anweisungen zu den Eigenschaften für Verweistypvariablen erstellen:C# 8.0 introduces nullable reference types and non-nullable reference types that enable you to make important statements about the properties for reference type variables:

  • Ein Verweis darf nicht NULL sein.A reference is not supposed to be null. Wenn Variablen nicht NULL sein dürfen, erzwingt der Compiler Regeln, die sicherstellen, dass das Dereferenzieren dieser Variablen sicher ist, ohne zuerst zu überprüfen, dass sie nicht NULL sind:When variables aren't supposed to be null, the compiler enforces rules that ensure it is safe to dereference these variables without first checking that it isn't null:
    • Die Variable muss mit einem Wert ungleich NULL initialisiert werden.The variable must be initialized to a non-null value.
    • Der Variablen kann nie der Wert null zugewiesen werden.The variable can never be assigned the value null.
  • Ein Verweis darf NULL sein.A reference may be null. Wenn Variablen NULL sein dürfen, erzwingt der Compiler verschiedene Regeln, um sicherzustellen, dass Sie richtig auf einen Nullverweis überprüft haben:When variables may be null, the compiler enforces different rules to ensure that you've correctly checked for a null reference:
    • Die Variable kann nur dereferenziert werden, wenn der Compiler garantieren kann, dass der Wert nicht NULL ist.The variable may only be dereferenced when the compiler can guarantee that the value isn't null.
    • Diese Variablen können mit dem Standardwert null initialisiert und in anderem Code dem Wert null zugewiesen werden.These variables may be initialized with the default null value and may be assigned the value null in other code.

Dieses neue Feature bietet große Vorteile hinsichtlich der Verarbeitung von Verweisvariablen in früheren Versionen von C#, bei denen die Entwurfsabsicht nicht über die Variablendeklaration bestimmt werden konnte.This new feature provides significant benefits over the handling of reference variables in earlier versions of C# where the design intent couldn't be determined from the variable declaration. Der Compiler bot keinen Schutz gegen Nullverweisausnahmen für Verweistypen:The compiler didn't provide safety against null reference exceptions for reference types:

  • Ein Verweis kann NULL sein.A reference can be null. Wenn ein Verweistyp mit NULL initialisiert oder später NULL zugewiesen wird, werden keine Warnungen ausgegeben.No warnings are issued when a reference type is initialized to null, or later assigned to null.
  • Es wird angenommen, dass ein Verweis nicht NULL ist.A reference is assumed to be not null. Der Compiler gibt keine Warnungen aus, wenn Verweistypen dereferenziert werden.The compiler doesn't issue any warnings when reference types are dereferenced. (Bei Nullable-Verweisen gibt der Compiler Warnungen aus, sobald Sie eine Variable dereferenzieren, die möglicherweise NULL ist).(With nullable references, the compiler issues warnings whenever you dereference a variable that may be null).

Durch das Hinzufügen von Nullable-Verweistypen können Sie Ihre Absicht klarer deklarieren.With the addition of nullable reference types, you can declare your intent more clearly. Der null-Wert ist die richtige Wahl, um darzustellen, dass eine Variable auf keinen Wert verweist.The null value is the correct way to represent that a variable doesn't refer to a value. Verwenden Sie dieses Feature nicht dazu, alle null-Werte aus Ihrem Code zu entfernen.Don't use this feature to remove all null values from your code. Stattdessen sollten Sie Ihre Absicht gegenüber dem Compiler und anderen Entwicklern deklarieren, die Ihren Code lesen.Rather, you should declare your intent to the compiler and other developers that read your code. Indem Sie Ihre Absicht deklarieren, werden Sie vom Compiler informiert, sobald Sie Code schreiben, der dieser Absicht widerspricht.By declaring your intent, the compiler informs you when you write code that is inconsistent with that intent.

Ein Nullable-Verweistyp wird mithilfe der gleichen Syntax wie Nullable-Werttypen aufgeführt: Ein ? wird an den Variablentyp angefügt.A nullable reference type is noted using the same syntax as nullable value types: a ? is appended to the type of the variable. Beispielsweise stellt die folgende Variablendeklaration eine Nullable-Zeichenfolgenvariable, name, dar:For example, the following variable declaration represents a nullable string variable, name:

string? name;

Bei jeder Variable, bei der ? nicht an den Typnamen angefügt ist, handelt es sich um einen Nicht-Nullable-Verweistyp.Any variable where the ? is not appended to the type name is a non-nullable reference type. Dies umfasst alle Verweistypvariablen in vorhandenem Code, wenn Sie dieses Feature aktiviert haben.That includes all reference type variables in existing code when you have enabled this feature.

Der Compiler verwendet die statische Analyse, um zu bestimmen, ob ein Nullable-Verweis nicht NULL ist.The compiler uses static analysis to determine if a nullable reference is known to be non-null. Der Compiler warnt Sie, falls Sie einen Nullable-Verweis dereferenzieren, wenn dieser möglicherweise NULL ist.The compiler warns you if you dereference a nullable reference when it may be null. Sie können dieses Verhalten überschreiben, indem Sie den NULL-toleranten Operator (!) gefolgt von einem Variablennamen verwenden.You can override this behavior by using the null-forgiving operator ! following a variable name. Wenn Sie beispielsweise wissen, dass die Variable name nicht NULL ist, der Compiler aber eine Warnung ausgibt, können Sie folgenden Code schreiben, um die Compileranalyse zu überschreiben:For example, if you know the name variable isn't null but the compiler issues a warning, you can write the following code to override the compiler's analysis:

name!.Length;

NULL-Zulässigkeit von TypenNullability of types

Jeder beliebige Verweistyp kann über eine von vier NULL-Zulässigkeiten verfügen, die beschreibt, wann Warnungen ausgegeben werden:Any reference type can have one of four nullabilities, which describes when warnings are generated:

  • Nonnullable (Nicht-Nullable): Variablen dieses Typs kann NULL nicht zugewiesen werden.Nonnullable: Null can't be assigned to variables of this type. Variablen dieses Typs müssen vor der Dereferenzierung nicht auf NULL überprüft werden.Variables of this type don't need to be null-checked before dereferencing.
  • Nullable: Variablen dieses Typs kann NULL zugewiesen werden.Nullable: Null can be assigned to variables of this type. Wenn Variablen dieses Typs dereferenziert werden, ohne dass zuvor auf null überprüft wurde, wird eine Warnung ausgegeben.Dereferencing variables of this type without first checking for null causes a warning.
  • Oblivious (Nichtbeachtend): Dies ist der Zustand vor C# 8.0.Oblivious: This is the pre-C# 8.0 state. Variablen dieses Typs können ohne Warnungen dereferenziert oder zugewiesen werden.Variables of this type can be dereferenced or assigned without warnings.
  • Unknown (Unbekannt): Diese NULL-Zulässigkeit ist im Allgemeinen für Typparameter gedacht, bei denen der Compiler von Einschränkungen nicht erfährt, dass der Typ nullable oder nicht-nullable sein muss.Unknown: This is generally for type parameters where constraints don't tell the compiler that the type must be nullable or nonnullable.

Die NULL-Zulässigkeit eines Typs in einer Variablendeklaration wird durch den Nullable-Kontext gesteuert, in der die Variable deklariert wird.The nullability of a type in a variable declaration is controlled by the nullable context in which the variable is declared.

Nullable-KontexteNullable contexts

Nullable-Kontexte ermöglichen eine differenzierte Steuerung der Interpretation von Verweistypvariablen durch den Compiler.Nullable contexts enable fine-grained control for how the compiler interprets reference type variables. Der Nullable-Anmerkungskontext jeder beliebigen Quellzeile ist aktiviert oder deaktiviert.The nullable annotation context of any given source line is either enabled or disabled. Der Compiler vor C# 8.0 hat Ihren gesamten Code in einem deaktivierten Nullable-Kontext kompiliert: Jeder Verweistyp kann NULL sein.You can think of the pre-C# 8.0 compiler as compiling all your code in a disabled nullable context: any reference type may be null. Der Kontext „nullable warnings“ (Nullable-Warnungen) kann ebenfalls aktiviert oder deaktiviert sein.The nullable warnings context may also be enabled or disabled. Der Nullable-Warnungskontext gibt die vom Compiler generierten Warnungen mithilfe der Flussanalyse an.The nullable warnings context specifies the warnings generated by the compiler using its flow analysis.

Der Nullable-Anmerkungskontext und der Nullable-Warnungskontext können für ein Projekt festgelegt werden, indem Sie das Nullable-Element in Ihrer CSPROJ-Datei verwenden.The nullable annotation context and nullable warning context can be set for a project using the Nullable element in your .csproj file. Dieses Element konfiguriert, wie der Compiler die NULL-Zulässigkeit von Typen interpretiert und welche Warnungen generiert werden.This element configures how the compiler interprets the nullability of types and what warnings are generated. Gültige Einstellungen sind folgende:Valid settings are:

  • enable: Der Nullable-Anmerkungskontext ist enabled (aktiviert).enable: The nullable annotation context is enabled. Der Nullable-Warnungskontext ist enabled (aktiviert).The nullable warning context is enabled.
    • Variablen eines Verweistyps wie string sind „non-nullable“ (nicht-nullable).Variables of a reference type, string for example, are non-nullable. Alle NULL-Zulässigkeitswarnungen sind „enabled“ (aktiviert).All nullability warnings are enabled.
  • warnings: Der Nullable-Anmerkungskontext ist disabled (deaktiviert).warnings: The nullable annotation context is disabled. Der Nullable-Warnungskontext ist enabled (aktiviert).The nullable warning context is enabled.
    • Variablen eines Verweistyps sind „oblivious“ (nichtbeachtend).Variables of a reference type are oblivious. Alle NULL-Zulässigkeitswarnungen sind „enabled“ (aktiviert).All nullability warnings are enabled.
  • annotations: Der Nullable-Anmerkungskontext ist enabled (aktiviert).annotations: The nullable annotation context is enabled. Der Nullable-Warnungskontext ist disabled (deaktiviert).The nullable warning context is disabled.
    • Variablen eines Verweistyps wie „string“ sind „non-nullable“ (nicht-nullable).Variables of a reference type, string for example, are non-nullable. Alle NULL-Zulässigkeitswarnungen sind „disabled“ (deaktiviert).All nullability warnings are disabled.
  • disable: Der Nullable-Anmerkungskontext ist disabled (deaktiviert).disable: The nullable annotation context is disabled. Der Nullable-Warnungskontext ist disabled (deaktiviert).The nullable warning context is disabled.
    • Variablen eines Verweistyps sind „oblivious“ (nichtbeachtend), wie in früheren Versionen von C#.Variables of a reference type are oblivious, just like earlier versions of C#. Alle NULL-Zulässigkeitswarnungen sind „disabled“ (deaktiviert).All nullability warnings are disabled.

Beispiel:Example:

<Nullable>enable</Nullable>

Sie können auch Anweisungen verwenden, um diese Kontexte überall in Ihrem Projekt festzulegen:You can also use directives to set these same contexts anywhere in your project:

  • #nullable enable: Legt den Nullable-Anmerkungskontext und den Nullable-Warnungskontext auf enabled (aktiviert) fest.#nullable enable: Sets the nullable annotation context and nullable warning context to enabled.
  • #nullable disable: Legt den Nullable-Anmerkungskontext und den Nullable-Warnungskontext auf disabled (deaktiviert) fest.#nullable disable: Sets the nullable annotation context and nullable warning context to disabled.
  • #nullable restore: Stellt die Projekteinstellungen für den Nullable-Anmerkungskontext und den Nullable-Warnungskontext wieder her.#nullable restore: Restores the nullable annotation context and nullable warning context to the project settings.
  • #nullable disable warnings: Legt den Nullable-Warnungskontext auf disabled (deaktiviert) fest.#nullable disable warnings: Set the nullable warning context to disabled.
  • #nullable enable warnings: Legt den Nullable-Warnungskontext auf enabled (aktiviert) fest.#nullable enable warnings: Set the nullable warning context to enabled.
  • #nullable restore warnings: Stellt die Projekteinstellungen für den Nullable-Warnungskontext wieder her.#nullable restore warnings: Restores the nullable warning context to the project settings.
  • #nullable disable annotations: Legt den Nullable-Anmerkungskontext auf disabled (deaktiviert) fest.#nullable disable annotations: Set the nullable annotation context to disabled.
  • #nullable enable annotations: Legt den Nullable-Anmerkungskontext auf enabled (aktiviert) fest.#nullable enable annotations: Set the nullable annotation context to enabled.
  • #nullable restore annotations: Stellt die Projekteinstellungen für den Anmerkungswarnungskontext wieder her.#nullable restore annotations: Restores the annotation warning context to the project settings.

Standardmäßig sind die Nullable-Anmerkungs- und -Warnungskontexte deaktiviert.By default, nullable annotation and warning contexts are disabled. Dies bedeutet, dass Ihr vorhandener Code ohne Änderungen und ohne Warnungen kompiliert wird.That means that your existing code compiles without changes and without generating any new warnings.

Nullable-AnmerkungskontextNullable annotation context

Der Compiler verwendet die folgenden Regeln in einem „disabled“-Nullable-Anmerkungskontext:The compiler uses the following rules in a disabled nullable annotation context:

  • Sie können keine Nullable-Verweise in einem „disabled“-Kontext deklarieren.You can't declare nullable references in a disabled context.
  • Alle Verweisvariablen können NULL zugewiesen werden.All reference variables may be assigned to null.
  • Wenn eine Variable eines Verweistyps dereferenziert wird, werden keine Warnungen generiert.No warnings are generated when a variable of a reference type is dereferenced.
  • Der NULL-tolerante Operator kann in einem „disabled“-Kontext nicht verwendet werden.The null-forgiving operator may not be used in a disabled context.

Das Verhalten ist wie bei früheren Versionen von C#.The behavior is the same as previous versions of C#.

Der Compiler verwendet die folgenden Regeln in einem „enabled“-Nullable-Anmerkungskontext:The compiler uses the following rules in an enabled nullable annotation context:

  • Jede Variable eines Verweistyps ist ein Nicht-Nullable-Verweis.Any variable of a reference type is a non-nullable reference.
  • Jeder Nicht-Nullable-Verweis kann sicher dereferenziert werden.Any non-nullable reference may be dereferenced safely.
  • Jeder Nullable-Verweistyp (aufgeführt durch ? nach dem Typ in der Variablendeklaration) kann NULL sein.Any nullable reference type (noted by ? after the type in the variable declaration) may be null. Durch die statische Analyse wird bestimmt, ob der Wert ungleich NULL ist, wenn er dereferenziert wird.Static analysis determines if the value is known to be non-null when it is dereferenced. Ist dies nicht der Fall, werden Sie vom Compiler gewarnt.If not, the compiler warns you.
  • Sie können den NULL-toleranten Operator verwenden, um zu deklarieren, dass ein Nullable-Verweis nicht NULL ist.You can use the null-forgiving operator to declare that a nullable reference isn't null.

In einem „enabled“-Nullable-Anmerkungskontext deklariert das an einen Verweistyp angefügte Zeichen ? einen Nullable-Verweistyp.In an enabled nullable annotation context, the ? character appended to a reference type declares a nullable reference type. Der NULL-tolerante Operator (!) kann an einen Ausdruck angefügt werden, um zu deklarieren, dass der Ausdruck nicht NULL ist.The null-forgiving operator ! may be appended to an expression to declare that the expression isn't null.

Nullable-WarnungskontextNullable warning context

Der Nullable-Warnungskontext unterscheidet sich vom Nullable-Anmerkungskontext.The nullable warning context is distinct from the nullable annotation context. Warnungen können selbst dann aktiviert sein, wenn die neuen Anmerkungen deaktiviert sind.Warnings can be enabled even when the new annotations are disabled. Der Compiler bestimmt mithilfe der statischen Flussanalyse den NULL-Zustand eines Verweises.The compiler uses static flow analysis to determine the null state of any reference. Der NULL-Zustand ist entweder not null (nicht NULL) oder maybe null (vielleicht NULL), wenn der Nullable-Warnungskontext nicht disabled (deaktiviert) ist.The null state is either not null or maybe null when the nullable warning context isn't disabled. Wenn Sie einen Verweis dereferenzieren, wenn der Compiler bestimmt hat, dass dessen Zustand maybe null (vielleicht NULL) lautet, löst der Compiler eine Warnung aus.If you dereference a reference when the compiler has determined it's maybe null, the compiler warns you. Der Status eines Verweises ist maybe null (vielleicht NULL), sofern der Compiler nicht eine der folgenden beiden Bedingungen bestimmen kann:The state of a reference is maybe null unless the compiler can determine one of two conditions:

  1. Die Variable wurde definitiv einem Wert ungleich NULL zugewiesen.The variable has been definitely assigned to a non-null value.
  2. Die Variable oder der Ausdruck wurde vor der Dereferenzierung auf NULL überprüft.The variable or expression has been checked against null before de-referencing it.

Der Compiler generiert Warnungen, wenn Sie eine Variable oder einen Ausdruck im Zustand maybe null (vielleicht NULL) dereferenzieren und der Nullable-Warnungskontext aktiviert ist.The compiler generates warnings whenever you dereference a variable or expression in a maybe null state when the nullable warning context is enabled. Darüber hinaus werden Warnungen generiert, wenn eine Variable oder ein Ausdruck im Zustand maybe null (vielleicht NULL) einem Nicht-Nullable-Verweistyp zugewiesen wird und der Nullable-Anmerkungskontext aktiviert ist.Furthermore, warnings are generated when a maybe null variable or expression is assigned to a nonnullable reference type in an enabled nullable annotation context.

Siehe auchSee also