可为 null 的引用类型（C# 引用）

项目
05/10/2023

注意

本文介绍可为 null 的引用类型。还可以声明可为 null 的值类型。

由于在可为 null 的感知上下文选择加入了代码，可以使用可为 null 的引用类型。可为 null 的引用类型、null 静态分析警告和 null 包容运算符是可选的语言功能。默认情况下，所有功能都将关闭。可为 null 的上下文在项目级使用生成设置进行控制，或在代码中使用 pragmas 进行控制。

重要

从 .NET 6 (C# 10) 开始的所有项目模板都为项目启用可为 null 的上下文。使用早期模板创建的项目不包含此元素，并且除非在项目文件中启用这些功能或使用 pragma，否则这些功能将关闭。

在可为 null 的感知上下文中：

引用类型 T 的变量必须用非 null 值进行初始化，并且不能为其分配可能为 null 的值。
引用类型 T? 的变量可以用 null 进行初始化，也可以分配 null，但在取消引用之前必须对照 null 进行检查。
类型为 T? 的变量 m 在应用 null 包容运算符时被认为是非空的，如 m! 中所示。

不可为 null 的引用类型 T 和可为 null 的引用类型 T? 之间的区别按照编译器对上述规则的解释强制执行的。类型为 T 的变量和类型为 T? 的变量由相同的 .NET 类型表示。下面的示例声明了一个不可为 null 的字符串和一个可为 null 的字符串，然后使用 null 包容运算符将一个值分配给不可为 null 的字符串：

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

变量 notNull 和 nullable 都由 String 类型表示。因为不可为 null 的类型和可为 null 的类型都存储为相同的类型，所以有几个位置不允许使用可为 null 的引用类型。通常，可为 null 的引用类型不能用作基类或实现的接口。可为 null 的引用类型不能用于任何对象创建或类型测试表达式。可为 null 的引用类型不能是成员访问表达式的类型。下面的示例说明了这些构造：

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

可为 null 的引用和静态分析

上一部分中的示例说明了可为 null 的引用类型的性质。可为 null 的引用类型不是新的类类型，而是对现有引用类型的注释。编译器使用这些注释来帮助你查找代码中潜在的 null 引用错误。不可为 null 的引用类型和可为 null 的引用类型在运行时没有区别。编译器不会为不可为 null 的引用类型添加任何运行时检查。这有利于编译时分析。编译器将生成警告，帮助你查找和修复代码中潜在的 null 错误。你需声明意向，如果代码违反该意向，编译器会发出警告。

在可为 null 的上下文中，编译器对任何引用类型的变量（可为 null 的和不可为 null 的）执行静态分析。编译器会跟踪每个引用变量的 null-state，即 not-null 或 maybe-null 。不可为 Null 的引用的默认状态为 not-null。可为 Null 的引用的默认状态为 maybe-null。

不可为 Null 的引用类型在取消引用时应该始终是安全的，因为它们的 null-state 是 not-null 。若强制执行该规则，如果不可为 null 的引用类型没有初始化为非 null 值，编译器将发出警告。必须在声明的位置分配局部变量。必须在字段初始化表达式或每个构造函数中为每个字段分配 not-null 值。如果将不可为 Null 的引用分配给状态为 maybe-null 的引用，编译器会发出警告。一般情况下，不可为 Null 的引用的状态为 not-null，在取消引用这些变量时不会发出警告。

注意

如果将 maybe-null 表达式分配给不可为 Null 的引用类型，编译器会生成警告。然后，编译器会针对该变量生成警告，直到将该变量分配给 not-null 表达式。

可为 null 的引用类型可以进行初始化或分配给 null。因此，静态分析必须在取消对变量的引用之前确定该变量的状态为 not-null。如果可为 Null 的引用的状态确定为 maybe-null，将其分配给不可为 Null 的引用变量会生成编译器警告。以下类显示了这些警告的示例：

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

以下代码段显示了编译器在使用此类时发出警告的位置：

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

前面的示例演示编译器的静态分析如何确定引用变量的 null-state。编译器对 null 检查和分配应用语言规则以通知其分析。编译器无法对方法或属性的语义进行假设。如果调用执行 null 检查的方法，则编译器无法得知这些方法会影响变量的 null-state。可以将属性添加到 API，以告知编译器有关参数和返回值的语义。这些属性已应用于 .NET Core 库中的许多常见 API。例如，IsNullOrEmpty 已经更新，编译器正确地将该方法解释为 null 检查。有关应用于 null-state 静态分析的属性的详细信息，请参阅有关可为 Null 的属性的文章。

设置可为 null 的上下文

可以通过两种方式控制可为 null 的上下文。在项目级别，可以添加 <Nullable>enable</Nullable> 项目设置。在单个 C# 源文件中，可以添加 #nullable enable 来启用可为 null 的上下文。请参阅关于设置可为 null 策略的文章。在 .NET 6 之前，新项目使用默认值 <Nullable>disable</Nullable>。从 .NET 6 开始，新项目将在项目文件中包含 <Nullable>enable</Nullable> 元素。

C# 语言规范

有关详细信息，请参阅 C# 语言规范的以下建议：

另请参阅

可以为 null 的值类型

通过

可为 null 的引用类型（C# 引用）

可为 null 的引用和静态分析

设置可为 null 的上下文

C# 语言规范

另请参阅

其他资源