Typy referencyjne dopuszczające wartość nullNullable reference types

C#8,0 wprowadza typy odwołań do wartości null i typy odwołań niedopuszczających wartości null , które umożliwiają wykonywanie ważnych instrukcji dotyczących właściwości dla zmiennych typu odwołania: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:

  • Odwołanie nie powinno mieć wartości null.A reference is not supposed to be null. Gdy zmienne nie powinny mieć wartości null, kompilator wymusza reguły, które gwarantują, że można bezpiecznie odwoływać się do tych zmiennych bez uprzedniego sprawdzenia, czy nie ma ona wartości null: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:
    • Zmienna musi być zainicjowana do wartości innej niż null.The variable must be initialized to a non-null value.
    • Do zmiennej nigdy nie można przypisać wartości null.The variable can never be assigned the value null.
  • Odwołanie może mieć wartość null.A reference may be null. Gdy zmienne mogą mieć wartość null, kompilator wymusza różne reguły, aby upewnić się, że prawidłowo sprawdzono odwołanie o wartości null:When variables may be null, the compiler enforces different rules to ensure that you've correctly checked for a null reference:
    • Zmienna może zostać wykorzystana tylko wtedy, gdy kompilator może zagwarantować, że wartość nie ma wartości null.The variable may only be dereferenced when the compiler can guarantee that the value isn't null.
    • Te zmienne mogą być inicjowane z wartością domyślną null i może być przypisana wartość null w innym kodzie.These variables may be initialized with the default null value and may be assigned the value null in other code.

Ta nowa funkcja zapewnia znaczne korzyści w porównaniu z obsługą zmiennych referencyjnych we wcześniejszych C# wersjach, w których nie można ustalić intencji projektu na podstawie deklaracji zmiennej.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. Kompilator nie zapewniał bezpieczeństwa przed wyjątkami odwołania o wartości null dla typów referencyjnych:The compiler didn't provide safety against null reference exceptions for reference types:

  • Odwołanie może mieć wartość null.A reference can be null. Żadne ostrzeżenia nie są wydawane, gdy typ odwołania jest zainicjowany do wartości null lub później przypisany do wartości null.No warnings are issued when a reference type is initialized to null, or later assigned to null.
  • Przyjęto, że odwołanie nie ma wartości null.A reference is assumed to be not null. Kompilator nie wystawia żadnych ostrzeżeń, gdy odwołania do typów odwołań.The compiler doesn't issue any warnings when reference types are dereferenced. (Z odwołaniami do wartości null, kompilator emituje ostrzeżenia za każdym razem, gdy odwołujesz się do zmiennej, która może mieć wartość null).(With nullable references, the compiler issues warnings whenever you dereference a variable that may be null).

Przy dodawaniu typów odwołań do wartości null można zadeklarować cel dokładniej.With the addition of nullable reference types, you can declare your intent more clearly. Wartość null jest prawidłowym sposobem reprezentowania, że zmienna nie odwołuje się do wartości.The null value is the correct way to represent that a variable doesn't refer to a value. Nie używaj tej funkcji, aby usunąć wszystkie wartości null z kodu.Don't use this feature to remove all null values from your code. Zamiast tego należy zadeklarować intencję do kompilatora i innych deweloperów, które odczytują swój kod.Rather, you should declare your intent to the compiler and other developers that read your code. Deklarując swój intencję, kompilator informuje, gdy piszesz kod, który jest niespójny z tym zamiarem.By declaring your intent, the compiler informs you when you write code that is inconsistent with that intent.

Typ referencyjny dopuszczający wartość null jest zanotowany przy użyciu tej samej składni co typ wartości null: ? jest dołączany do typu zmiennej.A nullable reference type is noted using the same syntax as nullable value types: a ? is appended to the type of the variable. Na przykład następująca deklaracja zmiennej reprezentuje zmienną ciągu dopuszczającą wartość null, name:For example, the following variable declaration represents a nullable string variable, name:

string? name;

Dowolna zmienna, w której ? nie jest dołączana do nazwy typu, jest typem referencyjnym, który nie dopuszcza wartości null.Any variable where the ? is not appended to the type name is a non-nullable reference type. Zawiera wszystkie zmienne typu odwołania w istniejącym kodzie po włączeniu tej funkcji.That includes all reference type variables in existing code when you have enabled this feature.

Kompilator używa statycznej analizy do ustalenia, czy odwołanie dopuszczające wartość null jest znane jako inne niż null.The compiler uses static analysis to determine if a nullable reference is known to be non-null. Kompilator ostrzega o tym, jeśli odwołujesz się do odwołania do wartości null, jeśli może to mieć wartość null.The compiler warns you if you dereference a nullable reference when it may be null. Można zastąpić to zachowanie przy użyciu operatora null-łagodniejszej ! po nazwie zmiennej.You can override this behavior by using the null-forgiving operator ! following a variable name. Na przykład jeśli wiesz, że zmienna name nie ma wartości null, ale kompilator generuje ostrzeżenie, można napisać następujący kod, aby zastąpić analizę kompilatora: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;

Wartość zerowa typówNullability of types

Każdy typ referencyjny może mieć jeden z czterech nullabilities, który opisuje, kiedy generowane są ostrzeżenia:Any reference type can have one of four nullabilities, which describes when warnings are generated:

  • Niedopuszczający wartości null: nie można przypisać wartości null do zmiennych tego typu.Nonnullable: Null can't be assigned to variables of this type. Przed usunięciem odwołania zmienne tego typu nie muszą mieć wartości null.Variables of this type don't need to be null-checked before dereferencing.
  • Nullable: wartość null może być przypisana do zmiennych tego typu.Nullable: Null can be assigned to variables of this type. Wycofaj odwołania do zmiennych tego typu bez uprzedniego sprawdzenia dla null powoduje ostrzeżenie.Dereferencing variables of this type without first checking for null causes a warning.
  • Oblivious: to jest stan sprzedC# 8,0.Oblivious: This is the pre-C# 8.0 state. Zmienne tego typu mogą być wywoływane lub przypisane bez ostrzeżeń.Variables of this type can be dereferenced or assigned without warnings.
  • Nieznane: zwykle w przypadku parametrów typu, w których ograniczenia nie informują kompilatora, że typ musi dopuszczać wartości null lub nie dopuszczać wartości null.Unknown: This is generally for type parameters where constraints don't tell the compiler that the type must be nullable or nonnullable.

Wartość null typu w deklaracji zmiennej jest kontrolowana przez kontekst dopuszczający wartość null, w którym zmienna jest zadeklarowana.The nullability of a type in a variable declaration is controlled by the nullable context in which the variable is declared.

Konteksty dopuszczające wartość nullNullable contexts

Konteksty dopuszczające wartość null umożliwiają precyzyjne kontrolowanie, w jaki sposób kompilator interpretuje zmienne typu odwołania.Nullable contexts enable fine-grained control for how the compiler interprets reference type variables. Kontekst adnotacji dopuszczający wartość null w dowolnym wierszu źródłowym jest włączony lub wyłączony.The nullable annotation context of any given source line is either enabled or disabled. Można traktować kompilatorC# przed8,0 jako kompilując cały kod w wyłączonym kontekście dopuszczający wartość null: dowolny typ referencyjny może mieć wartość null.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. Kontekst ostrzeżeń dopuszczających wartość null może być również włączony lub wyłączony.The nullable warnings context may also be enabled or disabled. Kontekst ostrzeżeń dopuszczających wartość null określa ostrzeżenia generowane przez kompilator przy użyciu analizy przepływu.The nullable warnings context specifies the warnings generated by the compiler using its flow analysis.

Kontekst adnotacji dopuszczający wartość null i kontekst ostrzeżenia dopuszczający wartość null można ustawić dla projektu przy użyciu elementu Nullable w pliku . csproj .The nullable annotation context and nullable warning context can be set for a project using the Nullable element in your .csproj file. Ten element określa, w jaki sposób kompilator interpretuje wartość null typów i jakie ostrzeżenia są generowane.This element configures how the compiler interprets the nullability of types and what warnings are generated. Prawidłowe ustawienia to:Valid settings are:

  • enable: kontekst adnotacji dopuszczający wartość null jest włączony.enable: The nullable annotation context is enabled. Kontekst ostrzegawczy dopuszczający wartość null jest włączony.The nullable warning context is enabled.
    • Zmienne typu referencyjnego, string na przykład, nie dopuszczają wartości null.Variables of a reference type, string for example, are non-nullable. Wszystkie ostrzeżenia o wartości null są włączone.All nullability warnings are enabled.
  • warnings: kontekst adnotacji dopuszczający wartość null jest wyłączony.warnings: The nullable annotation context is disabled. Kontekst ostrzegawczy dopuszczający wartość null jest włączony.The nullable warning context is enabled.
    • Zmienne typu referencyjnego to Oblivious.Variables of a reference type are oblivious. Wszystkie ostrzeżenia o wartości null są włączone.All nullability warnings are enabled.
  • annotations: kontekst adnotacji dopuszczający wartość null jest włączony.annotations: The nullable annotation context is enabled. Kontekst ostrzegawczy dopuszczający wartość null jest wyłączony.The nullable warning context is disabled.
    • Zmienne typu referencyjnego, ciąg na przykład, nie dopuszczają wartości null.Variables of a reference type, string for example, are non-nullable. Wszystkie ostrzeżenia o wartości null są wyłączone.All nullability warnings are disabled.
  • disable: kontekst adnotacji dopuszczający wartość null jest wyłączony.disable: The nullable annotation context is disabled. Kontekst ostrzegawczy dopuszczający wartość null jest wyłączony.The nullable warning context is disabled.
    • Zmienne typu referencyjnego to Oblivious, podobnie jak w przypadku wcześniejszych wersji C#programu.Variables of a reference type are oblivious, just like earlier versions of C#. Wszystkie ostrzeżenia o wartości null są wyłączone.All nullability warnings are disabled.

Przykład:Example:

<Nullable>enable</Nullable>

Możesz również użyć dyrektyw, aby ustawić te same konteksty w dowolnym miejscu w projekcie:You can also use directives to set these same contexts anywhere in your project:

  • #nullable enable: ustawia kontekst adnotacji dopuszczający wartość null i kontekst ostrzeżenia nullable do włączenia.#nullable enable: Sets the nullable annotation context and nullable warning context to enabled.
  • #nullable disable: ustawia kontekst adnotacji dopuszczający wartość null i kontekst ostrzeżenia dopuszczający wartość null.#nullable disable: Sets the nullable annotation context and nullable warning context to disabled.
  • #nullable restore: przywraca kontekst adnotacji dopuszczający wartość null i kontekst ostrzeżenia do wartości null w ustawieniach projektu.#nullable restore: Restores the nullable annotation context and nullable warning context to the project settings.
  • #nullable disable warnings: Ustaw wartość ustawienia kontekst ostrzeżenia o wartości null na wyłączony.#nullable disable warnings: Set the nullable warning context to disabled.
  • #nullable enable warnings: Ustaw dla kontekstu ostrzeżenia nullable wartość włączone.#nullable enable warnings: Set the nullable warning context to enabled.
  • #nullable restore warnings: przywraca kontekst ostrzegawczy dopuszczający wartość null do ustawień projektu.#nullable restore warnings: Restores the nullable warning context to the project settings.
  • #nullable disable annotations: Ustaw wartość opcji kontekst adnotacji dopuszczającej wartość null na wyłączony.#nullable disable annotations: Set the nullable annotation context to disabled.
  • #nullable enable annotations: Ustaw kontekst adnotacji dopuszczający wartość null.#nullable enable annotations: Set the nullable annotation context to enabled.
  • #nullable restore annotations: przywraca kontekst ostrzeżenia adnotacji do ustawień projektu.#nullable restore annotations: Restores the annotation warning context to the project settings.

Domyślnie w przypadku adnotacji z dopuszczaniem wartości null i kontekstów ostrzeżeń są wyłączone.By default, nullable annotation and warning contexts are disabled. Oznacza to, że istniejący kod kompiluje się bez zmian i nie generuje żadnych nowych ostrzeżeń.That means that your existing code compiles without changes and without generating any new warnings.

Kontekst adnotacji dopuszczający wartość nullNullable annotation context

Kompilator używa następujących reguł w wyłączonym kontekście adnotacji nullable:The compiler uses the following rules in a disabled nullable annotation context:

  • Nie można zadeklarować odwołań do wartości null w wyłączonym kontekście.You can't declare nullable references in a disabled context.
  • Wszystkie zmienne odwołania mogą być przypisane do wartości null.All reference variables may be assigned to null.
  • Nie są generowane żadne ostrzeżenia, gdy zmienna typu odwołania jest wykorzystana.No warnings are generated when a variable of a reference type is dereferenced.
  • Operatora null-łagodniejszej nie można używać w wyłączonym kontekście.The null-forgiving operator may not be used in a disabled context.

Zachowanie jest takie samo jak w poprzednich wersjach programu C#.The behavior is the same as previous versions of C#.

Kompilator używa następujących reguł w włączonym kontekście adnotacji dopuszczających wartość null:The compiler uses the following rules in an enabled nullable annotation context:

  • Dowolna zmienna typu referencyjnego jest odwołaniem niedopuszczanym do wartości null.Any variable of a reference type is a non-nullable reference.
  • Wszystkie odwołania niedopuszczające wartości null mogą być bezpiecznie wywoływać.Any non-nullable reference may be dereferenced safely.
  • Dowolny typ referencyjny dopuszczający wartość null (zanotowany przez ? po typie w deklaracji zmiennej) może mieć wartość null.Any nullable reference type (noted by ? after the type in the variable declaration) may be null. Analiza statyczna określa, czy wartość jest znana jako inna niż null, gdy jest ona wywoływać.Static analysis determines if the value is known to be non-null when it is dereferenced. W przeciwnym razie kompilator wyświetli ostrzeżenie.If not, the compiler warns you.
  • Można użyć operatora null-łagodniejszej, aby zadeklarować, że odwołanie dopuszczające wartość null nie ma wartości null.You can use the null-forgiving operator to declare that a nullable reference isn't null.

W włączonym kontekście dopuszczającym wartość null, znak ? dołączany do typu referencyjnego deklaruje typ referencyjny dopuszczający wartość null.In an enabled nullable annotation context, the ? character appended to a reference type declares a nullable reference type. ! operatora o wartości null może być dołączany do wyrażenia w celu stwierdzenia, że wyrażenie nie ma wartości null.The null-forgiving operator ! may be appended to an expression to declare that the expression isn't null.

Kontekst ostrzegawczy dopuszczający wartość nullNullable warning context

Kontekst ostrzeżenia dopuszczający wartość null jest różny od kontekstu adnotacji dopuszczającej wartość null.The nullable warning context is distinct from the nullable annotation context. Ostrzeżenia można włączyć nawet wtedy, gdy nowe adnotacje są wyłączone.Warnings can be enabled even when the new annotations are disabled. Kompilator używa statycznej analizy przepływu do określenia stanu null dowolnych odwołań.The compiler uses static flow analysis to determine the null state of any reference. Stan o wartości null nie ma wartości null lub może mieć wartość null , jeśli kontekst ostrzeżenia o wartości null nie jest wyłączony.The null state is either not null or maybe null when the nullable warning context isn't disabled. Jeśli odwołujesz się do odwołania, gdy kompilator ustalił, że może mieć wartość null, kompilator wyświetli ostrzeżenie.If you dereference a reference when the compiler has determined it's maybe null, the compiler warns you. Stan odwołania może mieć wartość null , chyba że kompilator może określić jeden z dwóch warunków:The state of a reference is maybe null unless the compiler can determine one of two conditions:

  1. Zmienna została ostatecznie przypisana do wartości innej niż null.The variable has been definitely assigned to a non-null value.
  2. Zmienna lub wyrażenie zostało sprawdzone pod kątem wartości null przed usunięciem odwołania do niego.The variable or expression has been checked against null before de-referencing it.

Kompilator generuje ostrzeżenia za każdym razem, gdy użytkownik odwołuje się do zmiennej lub wyrażenia w stanie null, gdy jest włączony kontekst ostrzeżenia z wartością null.The compiler generates warnings whenever you dereference a variable or expression in a maybe null state when the nullable warning context is enabled. Ponadto są generowane ostrzeżenia, gdy możliwa jest zmienna null lub wyrażenie jest przypisywane do niezerowego typu odwołania w włączonym kontekście adnotacji dopuszczających wartość null.Furthermore, warnings are generated when a maybe null variable or expression is assigned to a nonnullable reference type in an enabled nullable annotation context.

Zobacz takżeSee also