可为空引用类型

在为 null 性未知的上下文中，所有引用类型都可为 null。 可为 null 引用类型指的是已知可为 null 的上下文中引入的一组功能，可用于最大程度地降低代码导致运行时引发 System.NullReferenceException 的可能性。 可为 null 引用类型包括三项功能，可帮助避免这些异常，包括将引用类型显式标记为可为 null 的功能：

• 经过优化的静态流分析，用于在取消引用变量之前确定其是否为 null。
• 属性，用于注释 API 以便流分析确定 null 状态。
• 变量注释，可供开发人员用于显式声明变量的预期 null 状态。

对现有项目默认禁用 Null 状态分析和变量注释，这意味着所有引用类型仍为可为 null。 从 .NET 6 开始，默认情况下会为新项目启用这些功能。 有关通过声明可为 null 注释上下文来启用这些功能的信息，请参阅可为 null 上下文。

本文的其余部分介绍了当你的代码可能取消引用 null 值时，这三个功能区域如何生成警告。 取消引用变量意味着使用 .（点）运算符访问其成员之一，如下例所示：

string message = "Hello, World!";
int length = message.Length; // dereferencing "message"

取消引用值为 null 的变量时，运行时会引发 System.NullReferenceException。

还可以通过关于 C# 中可为 Null 的安全性的学习模块了解这些概念。

null 状态分析

Null 状态分析跟踪引用的 null 状态。 代码可能取消引用 null 时，此静态分析会发出警告。 你可处理这些警告，从而最大程度地减少运行时引发 System.NullReferenceException 的次数。 编译器使用静态分析来确定变量的 null 状态。 变量为“非 null”或“可能为 null” 。 编译器通过两种方式确定变量是否非 null：

1. 已为该变量分配一个已知非 NULL 的值。
2. 已检查该变量是否为 null，并且该变量自该检查后未进行过修改。

编译器未确定为非 null 的任何变量均视为“可能为 null” 。 如果意外取消引用 null 值，分析会发出警告。 编译器根据 null 状态生成警告。

• 变量为非 null 时，可安全地取消引用该变量。
• 变量可能为 null 时，必须先检查该变量，确保其不为 null，然后才能取消引用它。

请考虑以下示例：

string message = null;

// warning: dereference null.
Console.WriteLine($"The length of the message is {message.Length}");

var originalMessage = message;
message = "Hello, World!";

// No warning. Analysis determined "message" is not null.
Console.WriteLine($"The length of the message is {message.Length}");

// warning!
Console.WriteLine(originalMessage.Length);

在上例中，编译器在打印第一条消息时确定 message 是否可能为 null。 对于第二条消息，没有警告。 originalMessage 可能为 null，因此最后一行代码发出警告。 下面的示例演示了一个更实际的用途，即遍历节点树直到根，并在遍历过程中处理每个节点：

void FindRoot(Node node, Action<Node> processNode)
{
    for (var current = node; current != null; current = current.Parent)
    {
        processNode(current);
    }
}

上述代码不会因取消引用变量 current 而生成任何警告。 静态分析确定当 current 可能为 null 时永不会被取消引用。 访问 current.Parent 以及将 current 传递给 ProcessNode 操作之前，会检查变量 current 是否为 null。 上述示例演示了编译器如何在初始化、分配或与 null 比较时确定局部变量的 null 状态。

null 状态分析不会跟踪到调用的方法。 因此，构造函数调用的常见帮助程序方法中初始化的字段将使用以下模板生成警告：

在退出构造函数时，不可为 null 的属性“name”必须包含非 null 值。

可以通过以下两种方式之一消除这些警告：帮助程序方法上的构造函数链接或可以为 null 的属性。 下面的代码就是删除两种空格的示例。 Person 类使用由所有其他构造函数调用的通用构造函数。 Student 类具有使用 System.Diagnostics.CodeAnalysis.MemberNotNullAttribute 特性进行批注的帮助程序方法：

using System.Diagnostics.CodeAnalysis;

public class Person
{
    public string FirstName { get; set; }
    public string LastName { get; set; }

    public Person(string firstName, string lastName)
    {
        FirstName = firstName;
        LastName = lastName;
    }

    public Person() : this("John", "Doe") { }
}

public class Student : Person
{
    public string Major { get; set; }

    public Student(string firstName, string lastName, string major)
        : base(firstName, lastName)
    {
        SetMajor(major);
    }

    public Student(string firstName, string lastName) :
        base(firstName, lastName)
    {
        SetMajor();
    }

    public Student()
    {
        SetMajor();
    }

    [MemberNotNull(nameof(Major))]
    private void SetMajor(string? major = default)
    {
        Major = major ?? "Undeclared";
    }
}

可为 null 的状态分析和编译器生成的警告有助于通过取消引用 null 来避免程序错误。 有关可为 null 的警告的文章提供了用于更正代码中可能看到的警告的技术。

API 签名上的属性

null 状态分析需要开发人员的提示才能理解 API 的语义。 某些 API 提供 null 检查，它们应将变量的 null 状态从“可能为 null”更改为“非 null” 。 其他 API 返回非 null 或可能为 null 的表达式，具体取决于输入参数的 null 状态 。 例如，考虑显示消息的以下代码：

public void PrintMessage(string message)
{
    if (!string.IsNullOrWhiteSpace(message))
    {
        Console.WriteLine($"{DateTime.Now}: {message}");
    }
}

根据检查，所有开发人员都认为此代码安全，不应生成警告。 编译器不知道 IsNullOrWhiteSpace 提供 null 检查。 可应用属性来通知编译器当且仅当 IsNullOrWhiteSpace 返回 false 时 message 为非 null。 在上例中，签名包含 NotNullWhen 以指示 message 的 null 状态：

public static bool IsNullOrWhiteSpace([NotNullWhen(false)] string message);

属性详细说明了用于调用成员的对象实例的参数、返回值和成员的 null 状态。 若要详细了解每个属性，可查看关于可为 null 的引用属性的语言参考文章。 在 .NET 5 中，.NET 运行时 API 均带有注释。 可通过注释 API 提供有关参数和返回值的 null 状态的语义信息来优化静态分析。

可为 null 的变量注释

null 状态分析为大多数变量提供可靠的分析。 编译器需要你提供有关成员变量的更多信息。 编译器无法假定对公共成员的访问顺序。 可按任意顺序访问任何公共成员。 可使用任何可访问的构造函数来初始化对象。 如果某个成员字段曾设为 null，则编译器必须在每个方法开始时假定其 null 状态是“可能为 null” 。

可使用能够声明变量是可为 null 引用类型还是不可为 null 引用类型的注释 。 这些注释对变量的 null 状态进行重要声明：

• 引用不应为 null。 不可为 Null 的引用变量的默认状态为 not-null。 编译器会强制执行规则，确保即使不先检查变量是否为 null，也能安全地取消引用这些变量：
  • 必须将变量初始化为非 null 值。
  • 变量永远不能赋值为 null。 当代码将可能为 null 的表达式分配给不应为 null 的变量时，编译器会发出警告。
• 引用可为 null。 可为 Null 的引用变量的默认状态为 maybe-null。 编译器会强制执行规则，来确保已正确检查 null 引用：
  • 只有当编译器可保证该值不为 null 时，才可取消引用该变量。
  • 这些变量可以使用默认的 null 值进行初始化，也可以在其他代码中赋值为 null。
  • 代码将可能为 null 的表达式分配给可能为 null 的变量时，编译器不会发出警告。

任何不应为 null 的引用变量都具有非 null 的 null 状态 。 任何可能为 null 的引用变量最初都具有可能为 null 的 null 状态 。

使用与可为空值类型相同的语法记录可为空引用类型：将 ? 附加到变量的类型。 例如，以下变量声明表示可为空的字符串变量 name：

string? name;

未将 ? 附加到类型名称的任何变量都是“不可为 null 引用类型”。 这包括启用此功能时现有代码中的所有引用类型变量。 不过，任何隐式类型本地变量（使用 var 声明）都是可为 null 引用类型。 如上述部分所示，静态分析确定局部变量的 null 状态，从而确定其是否可能为 null 。

有时，当知道变量不为 null，但编译器确定其 null 状态是“可能为 null”时，必须覆盖警告 。 可在变量名称后使用 null 容忍操作符! 来将 null 状态强制为非 null。 例如，如果知道 name 变量不为 null，但编译器仍发出警告，你可编写以下代码来覆盖编译器的分析：

name!.Length;

可为 null 引用类型和可为 null 值类型提供类似的语义概念：变量可表示值或对象，或者该变量可以为 null。 但可为 null 引用类型和可为 null 值类型的实现方式不同：可为 null 值类型是使用 System.Nullable<T> 实现的，而可为 null 引用类型是使用编译器读取的属性实现的。 例如，string? 和 string 由同一类型表示：System.String。 但 int? 和 int 分别由 System.Nullable<System.Int32> 和 System.Int32 表示。

可为 null 的引用类型是编译时功能。 这意味着调用方可以忽略警告，故意使用 null 作为预期不可为 null 引用的方法的参数。 库作者应纳入针对 null 参数值的运行时检查。 这是 ArgumentNullException.ThrowIfNull 在运行时针对 null 检查参数的首选项。

泛型

泛型需要通过详细的规则来处理任何类型参数 T 的 T?。 由于历史原因以及可为 Null 的值类型和可为 Null 的引用类型的实现各不相同，这些规则必须详细。 可为 Null 的值类型是使用 System.Nullable<T> 结构实现的。 可为 Null 的引用类型实现为向编译器提供语义规则的类型注释。

• 如果 T 的类型参数为引用类型，则 T? 会引用相应的可为 Null 的引用类型。 例如，如果 T 是 string，则 T? 是 string?。
• 如果 T 的类型参数是值类型，则 T? 将引用相同的值类型 T。 例如，如果 T 是 int，则 T? 也是 int。
• 如果 T 的类型参数是可为 Null 的引用类型，则 T? 将引用相同的可为 Null 的引用类型。 例如，如果 T 是 string?，则 T? 也是 string?。
• 如果 T 的类型参数是可为 Null 的值类型，则 T? 将引用相同的可为 Null 的值类型。 例如，如果 T 是 int?，则 T? 也是 int?。

对于返回值，T? 等效于 [MaybeNull]T；对于参数值，T? 等效于 [AllowNull]T。 有关详细信息，请参阅语言参考中有关 null-state 分析的属性的文章。

可以使用约束指定不同的行为：

• class 约束意味着 T 必须是不可为 Null 的引用类型（例如 string）。 如果使用可为 Null 的引用类型（例如，为 T 使用 string?），编译器会生成警告。
• class? 约束意味着 T 必须是引用类型，可以是不可为 Null 的引用类型 (string)，也可以是可为 Null 的引用类型（例如 string?）。 当类型参数是可为 Null 的引用类型（例如 string?）时，T? 的表达式将引用相同的可为 Null 的引用类型（例如 string?）。
• notnull 约束意味着 T 必须是不可为 null 引用类型或不可为 null 值类型。 如果为类型参数使用可为 Null 的引用类型或可为 Null 的值类型，编译器会生成警告。 此外，当 T 是值类型时，返回值是该值类型，而不是相应的可为 Null 的值类型。

这些约束帮助为编译器提供有关如何使用 T 的更多信息。 这有助于开发人员为 T 选择类型，并且可在使用泛型类型的实例时提供更好的 null 状态分析。

可为空上下文

在现有代码库中，防止引发 System.NullReferenceException 的新功能在启用后可能会导致服务中断：

• 所有显式类型引用变量都均解释为不可为 null 引用类型。
• 泛型中 class 约束的含义已更改为表示不可为 null 引用类型。
• 由于这些新规则，将生成新警告。

必须在现有项目中明确选择使用这些功能。 这提供了迁移路径并保留了后向兼容性。 可为空上下文可以对编译器如何解释引用类型变量进行精细控制。 可为 null 注释上下文决定了编译器的行为。 可为 null 注释上下文有 4 个值：

• 禁用：代码的为 Null 性未知。
  • 禁用可为 null 警告。
  • 所有引用类型变量都是可为 null 引用类型。
  • 不能使用类型上的 ? 后缀将变量声明为可为 null 引用类型。
  • 可以使用 null 容忍运算符 !，但它不起任何作用。
• 启用：编译器启用所有 null 引用分析和所有语言功能。
  • 启用所有新的可为 null 警告。
  • 可使用 ? 后缀来声明可为 null 引用类型。
  • 所有其他引用类型变量都是不可为 null 引用类型。
  • null 容忍运算符禁止对可能的 null 赋值发出警告。
• 警告：当代码可能取消引用 null 时，编译器会执行所有 null 分析并发出警告。
  • 启用所有新的可为 null 警告。
  • 使用 ? 后缀来声明可为 null 引用类型会生成警告。
  • 所有引用类型变量均可为 null。 但是，除非使用 ? 后缀声明成员，否则成员在所有方法的左大括号处都具有非 null 的 null 状态 。
  • 可以使用 null 容忍运算符 !。
• 注释：当代码可能取消引用 null 时，编译器不会执行 null 分析，也不发出警告。
  • 禁用所有新的可为 null 警告。
  • 可使用 ? 后缀来声明可为 null 引用类型。
  • 所有其他引用类型变量都是不可为 null 引用类型。
  • 可以使用 null 容忍运算符 !，但它不起任何作用。

可以使用 .csproj 文件中的 <Nullable> 元素为项目设置可为 null 注释上下文和可为 null 警告上下文。 此元素配置编译器如何解释类型的为 Null 性以及发出哪些警告。 下表显示了允许的值并汇总了它们指定的上下文。

对于已禁用的上下文中编译的代码中的引用类型变量，其为 Null 性未知。 可将 null 文本或 maybe-null 变量分配给可为 Null 的未知类型的变量 。 但是，nullable-oblivious 变量的默认状态为 not-null 。

可选择最适合你的项目的设置：

• 对于根据诊断或新功能不想更新的旧项目，请选择“禁用”。
• 选择“警告”，确定代码可能引发 System.NullReferenceException 的位置。 可先处理这些警告，然后修改代码来启用不可为 null 引用类型。
• 选择“注释”来说明设计意图，然后启用警告。
• 对于希望避免出现 null 引用异常的新项目和活动项目，请选择“启用”。

示例：

<Nullable>enable</Nullable>

你还可使用指令在源代码的任何位置设置这些相同的上下文。 它们在迁移大型代码库时最有用。

• #nullable enable：将可为 null 的注释上下文和可为 null 的警告上下文设置为“启用”。
• #nullable disable：将可为 null 的注释上下文和可为 null 的警告上下文设置为“禁用”。
• #nullable restore：将可为空注释上下文和可为空警告上下文还原到项目设置。
• #nullable disable warnings：将可为 null 的警告上下文设置为“禁用”。
• #nullable enable warnings：将可为 null 的警告上下文设置为“启用”。
• #nullable restore warnings：将可为空警告上下文还原到项目设置。
• #nullable disable annotations：将可为 null 的注释上下文设置为“禁用”。
• #nullable enable annotations：将可为 null 的注释上下文设置为“启用”。
• #nullable restore annotations：将注释警告上下文还原到项目设置。

对于任何代码行，可设置以下任意组合：

通过这九种组合，可精细控制编译器为代码发出的诊断。 可在正在更新的任何区域中启用更多功能，这不会显示尚未准备好解决的其他警告。

默认情况下，可为空注释和警告上下文处于禁用状态。 这意味着无需更改现有代码即可进行编译，并且不会生成任何新警告。 从 .NET 6 开始，新项目在所有项目模板中都包含 <Nullable>enable</Nullable> 元素。

这些选项提供两种不同的策略来更新现有代码库以使用可为 null 的引用类型。

已知缺陷

包含引用类型的数组和结构是可为 null 引用中以及确定 null 安全性的静态分析中的已知缺陷。 在这两种情况下，不可为 null 引用均可初始化为 null，且不会生成警告。

结构

包含不可为 null 的引用类型的结构允许为其分配 default，而不会出现任何警告。 请考虑以下示例：

using System;

#nullable enable

public struct Student
{
    public string FirstName;
    public string? MiddleName;
    public string LastName;
}

public static class Program
{
    public static void PrintStudent(Student student)
    {
        Console.WriteLine($"First name: {student.FirstName.ToUpper()}");
        Console.WriteLine($"Middle name: {student.MiddleName?.ToUpper()}");
        Console.WriteLine($"Last name: {student.LastName.ToUpper()}");
    }

    public static void Main() => PrintStudent(default);
}

在前面的示例中，不可为 null 引用类型 FirstName 和 LastName 为 null 时，PrintStudent(default) 中未出现警告。

另一种较为常见的情况是处理泛型结构。 请考虑以下示例：

#nullable enable

public struct Foo<T>
{
    public T Bar { get; set; }
}

public static class Program
{
    public static void Main()
    {
        string s = default(Foo<string>).Bar;
    }
}

在前面的示例中，属性 Bar 在运行时将为 null，并被分配给不可为 null 的字符串，而未出现任何警告。

数组

数组也是可为 null 的引用类型中的已知缺陷。 请考虑以下示例，它不会生成任何警告：

using System;

#nullable enable

public static class Program
{
    public static void Main()
    {
        string[] values = new string[10];
        string s = values[0];
        Console.WriteLine(s.ToUpper());
    }
}

在前面的示例中，数组的声明显示它保留不可为 null 的字符串，而其元素都已初始化为 null。 然后，为变量 s 分配一个 null 值（数组的第一个元素）。 最后，取消引用变量 s，从而导致运行时异常。

请参阅

• 可为 Null 的引用类型建议
• 可为空引用类型规范草案
• 不受约束的类型参数批注
• 可为空引用教程简介
• Nullable（C# 编译器选项）