定义和读取自定义特性

使用特性，可以声明的方式将信息与代码相关联。 特性还可以提供能够应用于各种目标的可重用元素。 考虑 ObsoleteAttribute。 它可以应用于类、结构、方法、构造函数等。 用于声明元素已过时。 然后，由 C# 编译器负责查找此特性，并执行某响应操作。

此教程介绍如何将特性添加到代码中、如何创建和使用你自己的特性，以及如何使用一些内置到 .NET 中的特性。

先决条件

需要将计算机设置为运行 .NET。 有关安装说明，请访问 .NET 下载页。 可以在 Windows、Ubuntu Linux、macOS 或 Docker 容器中运行此应用程序。 需要安装常用的代码编辑器。 以下说明使用开放源代码跨平台编辑器 Visual Studio Code。 不过，可以使用习惯使用的任意工具。

创建应用

安装所有工具后，创建一个新的 .NET 控制台应用。 若要使用命令行生成器，请在常用的命令行管理程序中执行以下命令：

dotnet new console

此命令将创建最基本的 .NET 项目文件。 运行 dotnet restore 以还原编译此项目所需的依赖项。

无需运行 dotnet restore，因为它由所有需要还原的命令隐式运行，如 dotnet new、dotnet build、dotnet run、dotnet test、dotnet publish 和 dotnet pack。 若要禁用隐式还原，请使用 --no-restore 选项。

在执行显式还原有意义的某些情况下，例如 dotnet restore中，或在需要显式控制还原发生时间的生成系统中，dotnet restore 命令仍然有用。

有关如何使用 NuGet 源的信息，请参阅 dotnet restore 文档。

若要运行程序，请使用 dotnet run。 此时，应该可以在控制台中看到“Hello, World”输出。

将特性添加到代码中

在 C# 中，特性是继承自 Attribute 基类的类。 所有继承自 Attribute 的类都可以用作其他代码块的一种“标记”。 例如，有一个名为 ObsoleteAttribute 的特性。 此特性示意代码已过时，不得再使用。 将此特性应用于类（比如说，使用方括号）。

[Obsolete]
public class MyClass
{
}

虽然此类的名称为 ObsoleteAttribute，但只需在代码中使用 [Obsolete]。 大多数 C# 代码都遵循此约定。 如果愿意，也可以使用全名 [ObsoleteAttribute]。

如果将类标记为已过时，最好说明已过时的原因和/或改用的类。 在“已过时”特性中包含字符串参数以提供此说明。

[Obsolete("ThisClass is obsolete. Use ThisClass2 instead.")]
public class ThisClass
{
}

此字符串会作为参数传递给 ObsoleteAttribute 构造函数，就像在编写 var attr = new ObsoleteAttribute("some string") 一样。

只能向特性构造函数传递以下简单类型/文本类型参数：bool, int, double, string, Type, enums, etc和这些类型的数组。 不能使用表达式或变量。 可以使用任何位置参数或已命名参数。

创建你自己的特性

通过定义继承自 Attribute 基类的新类来创建特性。

public class MySpecialAttribute : Attribute
{
}

通过上述代码，可在基本代码中的其他位置将 [MySpecial]（或 [MySpecialAttribute]）用作特性。

[MySpecial]
public class SomeOtherClass
{
}

.NET 基类库中的特性（如 ObsoleteAttribute）会在编译器中触发某些行为。 不过，你创建的任何特性只作元数据之用，并不会在执行的特性类中生成任何代码。 是否在代码的其他位置使用此元数据由你自行决定。

这里要注意的是“gotcha”。 如前所述，使用特性时，只可将某些类型作为参数传递。 不过，在创建特性类型时，C# 编译器不会阻止你创建这些参数。 在以下示例中，你使用可正常编译的构造函数创建了一个特性。

public class GotchaAttribute : Attribute
{
    public GotchaAttribute(Foo myClass, string str)
    {
    }
}

不过，无法将此构造函数与特性语法结合使用。

[Gotcha(new Foo(), "test")] // does not compile
public class AttributeFail
{
}

上述代码导致一个编译器错误，例如 Attribute constructor parameter 'myClass' has type 'Foo', which is not a valid attribute parameter type

如何限制特性使用

特性可用于以下“目标”。 前面的示例展示了特性在类上的使用情况，而特性还可用于：

• 程序集
• 类
• 构造函数
• 委托
• 枚举
• 事件
• 字段
• 泛型参数
• 接口
• 方法
• 模块
• 参数
• properties
• 返回值
• 结构

创建特性类时，C# 默认允许对所有可能的特性目标使用此特性。 如果要将特性限制为只能用于特定目标，可以对特性类使用 AttributeUsageAttribute 来实现。 没错，就是将特性应用于特性！

[AttributeUsage(AttributeTargets.Class | AttributeTargets.Struct)]
public class MyAttributeForClassAndStructOnly : Attribute
{
}

如果尝试将上述特性应用于不是类也不是结构的对象，你会得到类似 Attribute 'MyAttributeForClassAndStructOnly' is not valid on this declaration type. It is only valid on 'class, struct' declarations 的编译器错误

public class Foo
{
    // if the below attribute was uncommented, it would cause a compiler error
    // [MyAttributeForClassAndStructOnly]
    public Foo()
    { }
}

如何使用附加到代码元素的特性

特性只作元数据之用。 不借助一些外在力量，特性其实什么用也没有。

若要查找特性并对其进行操作，需要使用反射。 通过反射，能够以 C# 编写检查其他代码的代码。 例如，可以使用反射获取类的相关信息（在代码开始处添加 using System.Reflection;）：

TypeInfo typeInfo = typeof(MyClass).GetTypeInfo();
Console.WriteLine("The assembly qualified name of MyClass is " + typeInfo.AssemblyQualifiedName);

输出如下内容：The assembly qualified name of MyClass is ConsoleApplication.MyClass, attributes, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null

获取 TypeInfo 对象（或 MemberInfo、FieldInfo 或其他对象）后，就可以使用 GetCustomAttributes 方法了。 此方法返回 Attribute 对象的集合。 还可以使用 GetCustomAttribute 并指定特性类型。

下面的示例展示了对 MyClass（在上文中，它包含 [Obsolete] 特性）的 MemberInfo 实例使用 GetCustomAttributes。

var attrs = typeInfo.GetCustomAttributes();
foreach(var attr in attrs)
    Console.WriteLine("Attribute on MyClass: " + attr.GetType().Name);

输出到控制台：Attribute on MyClass: ObsoleteAttribute。 请尝试向 MyClass 添加其他特性。

请务必注意，这些 Attribute 对象的实例化有延迟。 也就是说，只有使用 GetCustomAttribute 或 GetCustomAttributes，它们才会实例化。 这些对象每次都会实例化。 连续两次调用 GetCustomAttributes 返回两个不同的 ObsoleteAttribute 实例。

运行时中的常见特性

许多工具和框架都会使用特性。 NUnit 和 NUnit 测试运行程序都使用 [Test] 和 [TestFixture] 之类的特性。 ASP.NET MVC 使用 [Authorize] 之类的特性，并提供可密切关注 MVC 操作的操作筛选器框架。 PostSharp 使用特性语法，支持在 C# 中进行面向特性的编程。

下面介绍了一些值得注意的 .NET Core 基类库内置特性：

• [Obsolete]。 此特性已在上面的示例中使用过，位于 System 命名空间中。 可用于提供关于不断变化的基本代码的声明性文档。 可以提供字符串形式的消息，并能使用另一布尔参数将编译器警告升级为编译器错误。
• [Conditional]。 此特性位于 System.Diagnostics 命名空间中。 可应用于方法（或特性类）。 必须向构造函数传递字符串。 如果该字符串与 #define 指令不匹配，则 C# 编译器将删除对该方法（而不是方法本身）的所有调用。 通常，使用此方法进行调试（诊断）目的。
• [CallerMemberName]。 此特性可应用于参数，位于 System.Runtime.CompilerServices 命名空间中。 CallerMemberName 特性用于插入正在调用另一方法的方法的名称。 这是在各种 UI 框架中实现 INotifyPropertyChanged 时清除“神奇字符串”的一种方式。 示例：

public class MyUIClass : INotifyPropertyChanged
{
    public event PropertyChangedEventHandler? PropertyChanged;

    public void RaisePropertyChanged([CallerMemberName] string propertyName = default!)
    {
        PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(propertyName));
    }

    private string? _name;
    public string? Name
    {
        get { return _name;}
        set
        {
            if (value != _name)
            {
                _name = value;
                RaisePropertyChanged();   // notice that "Name" is not needed here explicitly
            }
        }
    }
}

在上面的代码中，无需使用文本类型 "Name" 字符串。 使用 CallerMemberName 可防止出现与拼写错误相关的 bug，也可以让重构/重命名操作变得更加顺畅。 特性为 C# 带来了声明性能力，但它们是一种元数据形式的代码，本身并不执行操作。