Typy referencyjne dopuszczające wartość nullNullable reference types

W języku C# 8,0 wprowadzono wartości null typów referencyjnych i 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 isn't supposed to be null. Gdy zmienne nie powinny mieć wartości null, kompilator wymusza reguły, które zapewnią bezpieczne odtworzenie odwołania do tych zmiennych bez uprzedniego sprawdzenia, czy nie ma on wartości null:When variables aren't supposed to be null, the compiler enforces rules that ensure it's 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 null wartością domyślną i mogą mieć przypisaną 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 wersjach języka C#, w których nie można ustalić zamiaru projektowania 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 can'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. Kompilator nie wydaje ostrzeżeń, gdy typ odwołania jest zainicjowany do wartości null lub później przypisany do wartości null.The compiler doesn't issue warnings when a reference type is initialized to null, or later assigned to null. Kompilator wystawia ostrzeżenia, gdy te zmienne są wywołujące bez sprawdzania wartości null.The compiler issues warnings when these variables are dereferenced without null checks.
  • 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. Kompilator wystawia ostrzeżenia, jeśli zmienna jest ustawiona na wyrażenie, które może mieć wartość null.The compiler issues warnings if a variable is set to an expression that may be null.

Te ostrzeżenia są emitowane w czasie kompilacji.These warnings are emitted at compile time. Kompilator nie dodaje żadnych kontroli wartości null ani innych konstrukcji środowiska uruchomieniowego w kontekście dopuszczającym wartość null.The compiler doesn't add any null checks or other runtime constructs in a nullable context. W czasie wykonywania, odwołanie do wartości null i odwołanie niedopuszczające wartości null są równoważne.At runtime, a nullable reference and a non-nullable reference are equivalent.

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. nullWartość jest poprawnym 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 null wartości z Twojego 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 typy wartości null: a ? 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 null, name :For example, the following variable declaration represents a nullable string variable, name:

string? name;

Każda 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 ? isn't appended to the type name is a non-nullable reference type. Zawiera wszystkie zmienne typu referencyjnego w istniejącym kodzie po włączeniu tej funkcji.That includes all reference type variables in existing code when you've 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. Zachowanie to można zastąpić za pomocą operatora null-łagodniejszej ! po nazwie zmiennej.You can override this behavior by using the null-forgiving operator ! following a variable name. Jeśli na przykład wiadomo, że name zmienna 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. Odwołujące się do zmiennych tego typu bez uprzedniego sprawdzenia null powoduje ostrzeżenie.Dereferencing variables of this type without first checking for null causes a warning.
  • Oblivious: Oblivious jest stanem sprzed C # 8,0.Oblivious: Oblivious 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.
  • Nieznany: nieznany jest zazwyczaj dla parametrów typu, w których ograniczenia nie informują kompilatora, że typ musi dopuszczać wartości null lub nie dopuszczać wartości null.Unknown: Unknown 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ć kompilator pre-C # 8,0 jako Kompilowanie całego kodu w wyłączonym kontekście dopuszczania wartości 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 Nullable elementu 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 z dopuszczaniem wartości 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 z dopuszczaniem wartości 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 języka C#.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 dla kontekstu ostrzeżenia o wartości null wartość wyłączone.#nullable disable warnings: Set the nullable warning context to disabled.
  • #nullable enable warnings: Ustaw kontekst ostrzegawczy dopuszczający wartość null.#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 dla kontekstu adnotacji wartości null wartość wyłączone.#nullable disable annotations: Set the nullable annotation context to disabled.
  • #nullable enable annotations: Ustaw dla kontekstu adnotacji nullable wartość włączone.#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 adnotacja null i konteksty ostrzeżeń są wyłączone, w tym nowych projektów.By default, nullable annotation and warning contexts are disabled, including new projects. 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.

Te opcje zapewniają dwie odrębne strategie aktualizowania istniejącej bazy kodu w celu użycia typów referencyjnych dopuszczających wartość null.These options provide two distinct strategies to update an existing codebase to use nullable reference types.

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ą mieć przypisaną wartość null.All reference variables may be assigned a value of 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 języka 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's 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łączony 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. Operator null-łagodniejszej ! może być dołączany do wyrażenia, aby zadeklarować, ż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, gdy zostanie wykorzystana zmienna lub wyrażenie, które może mieć wartość null w kontekście ostrzeżenia o wartości null.The compiler generates warnings when you dereference a variable or expression that is maybe null in a nullable warning context. Ponadto kompilator generuje ostrzeżenia, gdy typ odwołania, który ma wartość null, jest przypisany do zmiennej lub wyrażenia o wartości null w włączonym kontekście adnotacji typu null.Furthermore, the compiler generates warnings when a nonnullable reference type is assigned to a maybe null variable or expression in an enabled nullable annotation context.

Opisy interfejsów APIAttributes describe APIs

Dodaj atrybuty do interfejsów API, które udostępniają kompilatorowi więcej informacji na temat sytuacji, gdy argumenty lub wartości zwracane mogą lub nie mogą mieć wartości null.You add attributes to APIs that provide the compiler more information about when arguments or return values can or can't be null. Więcej informacji o tych atrybutach można znaleźć w naszym artykule w dokumentacji języka obejmującej atrybuty dopuszczające wartość null.You can learn more about these attributes in our article in the language reference covering the nullable attributes. Te atrybuty są dodawane do bibliotek .NET za pośrednictwem bieżących i przyszłych wersji.These attributes are being added to .NET libraries over current and upcoming releases. Najczęściej używane interfejsy API są aktualizowane jako pierwsze.The most commonly used APIs are being updated first.

Zobacz takżeSee also