类型参数的约束（C# 编程指南）

项目
08/01/2024

约束告知编译器类型参数必须具备的功能。在没有任何约束的情况下，类型参数可以是任何类型。编译器只能假定 System.Object 的成员，它是任何 .NET 类型的最终基类。有关详细信息，请参阅使用约束的原因。如果客户端代码使用不满足约束的类型，编译器将发出错误。通过使用 where 上下文关键字指定约束。下表列出了各种类型的约束：

约束	说明
`where T : struct`	类型参数必须是不可为 null 的值类型，其中包含 `record struct` 类型。有关可为 null 的值类型的信息，请参阅可为 null 的值类型。由于所有值类型都具有可访问的无参数构造函数（无论是声明的还是隐式的），因此 `struct` 约束表示 `new()` 约束，并且不能与 `new()` 约束结合使用。 `struct` 约束也不能与 `unmanaged` 约束结合使用。
`where T : class`	类型参数必须是引用类型。此约束还应用于任何类、接口、委托或数组类型。在可为 null 的上下文中，`T` 必须是不可为 null 的引用类型。
`where T : class?`	类型参数必须是可为 null 或不可为 null 的引用类型。此约束还应用于任何类、接口、委托或数组类型（包括记录）。
`where T : notnull`	类型参数必须是不可为 null 的类型。参数可以是不可为 null 的引用类型，也可以是不可为 null 的值类型。
`where T : unmanaged`	类型参数必须是不可为 null 的非托管类型。 `unmanaged` 约束表示 `struct` 约束，且不能与 `struct` 约束或 `new()` 约束结合使用。
`where T : new()`	类型参数必须具有公共无参数构造函数。与其他约束一起使用时，`new()` 约束必须最后指定。 `new()` 约束不能与 `struct` 和 `unmanaged` 约束结合使用。
`where T :` <基类名>	类型参数必须是指定的基类或派生自指定的基类。在可为 null 的上下文中，`T` 必须是从指定基类派生的不可为 null 的引用类型。
`where T :` <基类名>？	类型参数必须是指定的基类或派生自指定的基类。在可为 null 的上下文中，`T` 可以是从指定基类派生的可为 null 或不可为 null 的类型。
`where T :` <接口名>	类型参数必须是指定的接口或实现指定的接口。可指定多个接口约束。约束接口也可以是泛型。在的可为 null 的上下文中，`T` 必须是实现指定接口的不可为 null 的类型。
`where T :` <接口名>？	类型参数必须是指定的接口或实现指定的接口。可指定多个接口约束。约束接口也可以是泛型。在可为 null 的上下文中，`T` 可以是可为 null 的引用类型、不可为 null 的引用类型或值类型。 `T` 不能是可为 null 的值类型。
`where T : U`	为 `T` 提供的类型参数必须是为 `U` 提供的参数或派生自为 `U` 提供的参数。在可为 null 的上下文中，如果 `U` 是不可为 null 的引用类型，`T` 必须是不可为 null 的引用类型。如果 `U` 是可为 null 的引用类型，则 `T` 可以是可为 null 的引用类型，也可以是不可为 null 的引用类型。
`where T : default`	重写方法或提供显式接口实现时，如果需要指定不受约束的类型参数，此约束可解决歧义。 `default` 约束表示基方法，但不包含 `class` 或 `struct` 约束。有关详细信息，请参阅`default`约束规范建议。
`where T : allows ref struct`	此反约束声明 `T` 的类型参数可以是 `ref struct` 类型。该泛型类型或方法必须遵循 `T` 的任何实例的引用安全规则，因为它可能是 `ref struct`。

某些约束是互斥的，而某些约束必须按指定顺序排列：

最多可应用 struct、class、class?、notnull 和 unmanaged 约束中的一个。如果提供这些约束中的任何一个，则它必须是为该类型参数指定的第一个约束。
基类约束（where T : Base 或 where T : Base?）不能与 struct、class、class?、notnull 或 unmanaged 约束中的任何一个结合使用。
无论哪种形式，都最多只能应用一个基类约束。如果想要支持可为 null 的基类型，请使用 Base?。
不能将接口不可为 null 和可为 null 的形式命名为约束。
new() 约束不能与 struct 或 unmanaged 约束结合使用。如果指定 new() 约束，则它必须是该类型参数的最后一个约束。反约束（如果适用）可以遵循 new() 约束。
default 约束只能应用于替代或显式接口实现。它不能与 struct 或 class 约束结合使用。
allows ref struct 反约束不能与 class 或 class? 约束结合使用。
allows ref struct 反约束必须遵循该类型参数的所有约束。

使用约束的原因

约束指定类型参数的功能和预期。声明这些约束意味着你可以使用约束类型的操作和方法调用。如果泛型类或方法对泛型成员使用除简单赋值之外的任何操作，包括调用 System.Object 不支持的任何方法，则对类型参数应用约束。例如，基类约束告诉编译器，只有此类型的对象或派生自此类型的对象可替换该类型参数。编译器有了此保证后，就能够允许在泛型类中调用该类型的方法。以下代码示例演示可通过应用基类约束添加到（泛型介绍中的）GenericList<T> 类的功能。

public class Employee
{
    public Employee(string name, int id) => (Name, ID) = (name, id);
    public string Name { get; set; }
    public int ID { get; set; }
}

public class GenericList<T> where T : Employee
{
    private class Node
    {
        public Node(T t) => (Next, Data) = (null, t);

        public Node? Next { get; set; }
        public T Data { get; set; }
    }

    private Node? head;

    public void AddHead(T t)
    {
        Node n = new Node(t) { Next = head };
        head = n;
    }

    public IEnumerator<T> GetEnumerator()
    {
        Node? current = head;

        while (current != null)
        {
            yield return current.Data;
            current = current.Next;
        }
    }

    public T? FindFirstOccurrence(string s)
    {
        Node? current = head;
        T? t = null;

        while (current != null)
        {
            //The constraint enables access to the Name property.
            if (current.Data.Name == s)
            {
                t = current.Data;
                break;
            }
            else
            {
                current = current.Next;
            }
        }
        return t;
    }
}

约束使泛型类能够使用 Employee.Name 属性。约束指定类型 T 的所有项都保证是 Employee 对象或从 Employee 继承的对象。

可以对同一类型参数应用多个约束，并且约束自身可以是泛型类型，如下所示：

class EmployeeList<T> where T : notnull, Employee, IComparable<T>, new()
{
    // ...
    public void AddDefault()
    {
        T t = new T();
        // ...
    }
}

在应用 where T : class 约束时，请避免对类型参数使用 == 和 != 运算符，因为这些运算符仅测试引用标识而不测试值相等性。即使在用作参数的类型中重载这些运算符也会发生此行为。下面的代码说明了这一点；即使 String 类重载 == 运算符，输出也为 false。

public static void OpEqualsTest<T>(T s, T t) where T : class
{
    System.Console.WriteLine(s == t);
}

private static void TestStringEquality()
{
    string s1 = "target";
    System.Text.StringBuilder sb = new System.Text.StringBuilder("target");
    string s2 = sb.ToString();
    OpEqualsTest<string>(s1, s2);
}

编译器只知道 T 在编译时是引用类型，并且必须使用对所有引用类型都有效的默认运算符。如果必须测试值相等性，请应用 where T : IEquatable<T> 或 where T : IComparable<T> 约束，并在用于构造泛型类的任何类中实现该接口。

约束多个参数

可以对多个参数应用多个约束，对一个参数应用多个约束，如下例所示：

class Base { }
class Test<T, U>
    where U : struct
    where T : Base, new()
{ }

未绑定的类型参数

没有约束的类型参数（如公共类 SampleClass<T>{} 中的 T）称为未绑定的类型参数。未绑定的类型参数具有以下规则：

不能使用 != 和 == 运算符，因为无法保证具体的类型参数能支持这些运算符。
可以在它们与 System.Object 之间来回转换，或将它们显式转换为任何接口类型。
可以将它们与 null 进行比较。将未绑定的参数与 null 进行比较时，如果类型参数为值类型，则该比较始终返回 false。

类型参数作为约束

在具有自己类型参数的成员函数必须将该参数约束为包含类型的类型参数时，将泛型类型参数用作约束非常有用，如下例所示：

public class List<T>
{
    public void Add<U>(List<U> items) where U : T {/*...*/}
}

在上述示例中，T 在 Add 方法的上下文中是一个类型约束，而在 List 类的上下文中是一个未绑定的类型参数。

类型参数还可在泛型类定义中用作约束。必须在尖括号中声明该类型参数以及任何其他类型参数：

//Type parameter V is used as a type constraint.
public class SampleClass<T, U, V> where T : V { }

类型参数作为泛型类的约束的作用非常有限，因为编译器除了假设类型参数派生自 System.Object 以外，不会做其他任何假设。如果要在两个类型参数之间强制继承关系，可以将类型参数用作泛型类的约束。

`notnull` 约束

可以使用 notnull 约束指定类型参数必须是不可为 null 的值类型或不可为 null 的引用类型。与大多数其他约束不同，如果类型参数违反 notnull 约束，编译器会生成警告而不是错误。

notnull 约束仅在可为 null 上下文中使用时才有效。如果在过时的可为 null 上下文中添加 notnull 约束，编译器不会针对违反约束的情况生成任何警告或错误。

`class` 约束

可为 null 的上下文中的 class 约束指定类型参数必须是不可为 null 的引用类型。在可为 null 上下文中，当类型参数是可为 null 的引用类型时，编译器会生成警告。

`default` 约束

添加可为空引用类型会使泛型类型或方法中的 T? 使用复杂化。 T? 可以与 struct 或 class 约束一起使用，但必须存在其中一项。使用 class 约束时，T? 引用了 T 的可为空引用类型。可在这两个约束均未应用时使用 T?。在这种情况下，对于值类型和引用类型，T? 解读为 T?。但是，如果 T 是 Nullable<T>的实例，则 T? 与 T 相同。换句话说，它不会成为 T??。

由于现在可在没有 class 或 struct 约束的情况下使用 T?，因此在重写或显式接口实现中可能会出现歧义。在这两种情况下，重写不包含约束，但从基类继承。当基类不应用 class 或 struct 约束时，派生类需要通过某种方式在不使用任一种约束的情况下指定应用于基方法的重写。派生方法应用 default 约束。 default 约束不阐明 class 和 struct 约束。

非托管约束

可使用 unmanaged 约束来指定类型参数必须是不可为 null 的非托管类型。通过 unmanaged 约束，用户能编写可重用例程，从而使用可作为内存块操作的类型，如以下示例所示：

unsafe public static byte[] ToByteArray<T>(this T argument) where T : unmanaged
{
    var size = sizeof(T);
    var result = new Byte[size];
    Byte* p = (byte*)&argument;
    for (var i = 0; i < size; i++)
        result[i] = *p++;
    return result;
}

以上方法必须在 unsafe 上下文中编译，因为它并不是在已知的内置类型上使用 sizeof 运算符。如果没有 unmanaged 约束，则 sizeof 运算符不可用。

unmanaged 约束表示 struct 约束，且不能与其结合使用。因为 struct 约束表示 new() 约束，且 unmanaged 约束也不能与 new() 约束结合使用。

委托约束

可以使用 System.Delegate 或 System.MulticastDelegate 作为基类约束。 CLR 始终允许此约束，但 C# 语言不允许。使用 System.Delegate 约束，用户能够以类型安全的方式编写使用委托的代码。以下代码定义了合并两个同类型委托的扩展方法：

public static TDelegate? TypeSafeCombine<TDelegate>(this TDelegate source, TDelegate target)
    where TDelegate : System.Delegate
    => Delegate.Combine(source, target) as TDelegate;

可使用上述方法来合并相同类型的委托：

Action first = () => Console.WriteLine("this");
Action second = () => Console.WriteLine("that");

var combined = first.TypeSafeCombine(second);
combined!();

Func<bool> test = () => true;
// Combine signature ensures combined delegates must
// have the same type.
//var badCombined = first.TypeSafeCombine(test);

如果对最后一行取消注释，它将不会编译。 first 和 test 均为委托类型，但它们是不同的委托类型。

枚举约束

还可指定 System.Enum 类型作为基类约束。 CLR 始终允许此约束，但 C# 语言不允许。使用 System.Enum 的泛型提供类型安全的编程，缓存使用 System.Enum 中静态方法的结果。以下示例查找枚举类型的所有有效的值，然后生成将这些值映射到其字符串表示形式的字典。

public static Dictionary<int, string> EnumNamedValues<T>() where T : System.Enum
{
    var result = new Dictionary<int, string>();
    var values = Enum.GetValues(typeof(T));

    foreach (int item in values)
        result.Add(item, Enum.GetName(typeof(T), item)!);
    return result;
}

Enum.GetValues 和 Enum.GetName 使用反射，这会对性能产生影响。可调用 EnumNamedValues 来生成可缓存和重用的集合，而不是重复执行需要反射才能实施的调用。

如以下示例所示，可使用它来创建枚举并生成其值和名称的字典：

enum Rainbow
{
    Red,
    Orange,
    Yellow,
    Green,
    Blue,
    Indigo,
    Violet
}

var map = EnumNamedValues<Rainbow>();

foreach (var pair in map)
    Console.WriteLine($"{pair.Key}:\t{pair.Value}");

类型参数实现声明的接口

某些场景要求为类型参数提供的参数实现该接口。例如：

public interface IAdditionSubtraction<T> where T : IAdditionSubtraction<T>
{
    static abstract T operator +(T left, T right);
    static abstract T operator -(T left, T right);
}

此模式使 C# 编译器能够确定重载运算符或任何 static virtual 或 static abstract 方法的包含类型。它提供的语法使得可以在包含类型上定义加法和减法运算符。如果没有此约束，需要将参数和自变量声明为接口，而不是类型参数：

public interface IAdditionSubtraction<T> where T : IAdditionSubtraction<T>
{
    static abstract IAdditionSubtraction<T> operator +(
        IAdditionSubtraction<T> left,
        IAdditionSubtraction<T> right);

    static abstract IAdditionSubtraction<T> operator -(
        IAdditionSubtraction<T> left,
        IAdditionSubtraction<T> right);
}

上述语法要求实现者对这些方法使用显式接口实现。提供额外的约束使接口能够根据类型参数来定义运算符。实现接口的类型可以隐式实现接口方法。

Allows ref struct

allows ref struct 反约束声明相应的类型参数可以是 ref struct 类型。该类型参数的实例必须遵循以下规则：

它不能被装箱。
它参与引用安全规则。
不能在不允许 ref struct 类型的地方使用实例，例如 static 字段。
实例可以使用 scoped 修饰符进行标记。

不会继承 allows ref struct 子句。在以下代码中：

class SomeClass<T, S>
    where T : allows ref struct
    where S : T
{
    // etc
}

S 的参数不能是 ref struct，因为 S 没有 allows ref struct 子句。

具有 allows ref struct 子句的类型参数不能用作类型参数，除非相应的类型参数也具有 allows ref struct 子句。下面的示例说明了此规则：

public class Allow<T> where T : allows ref struct
{

}

public class Disallow<T>
{
}

public class Example<T> where T : allows ref struct
{
    private Allow<T> fieldOne; // Allowed. T is allowed to be a ref struct

    private Disallow<T> fieldTwo; // Error. T is not allowed to be a ref struct
}

前面的示例表明，对于一个可能是 ref struct 类型的类型参数，不能将其替换为不能是 ref struct 类型的类型参数。

通过

类型参数的约束（C# 编程指南）

使用约束的原因

约束多个参数

未绑定的类型参数

类型参数作为约束

`notnull` 约束

`class` 约束

`default` 约束

非托管约束

委托约束

枚举约束

类型参数实现声明的接口

Allows ref struct

另请参阅

其他资源

通过

类型参数的约束（C# 编程指南）

使用约束的原因

约束多个参数

未绑定的类型参数

类型参数作为约束

notnull 约束

class 约束

default 约束

非托管约束

委托约束

枚举约束

类型参数实现声明的接口

Allows ref struct

另请参阅

其他资源

`notnull` 约束

`class` 约束

`default` 约束