windows C#-定义和读取自定义特性

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

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

创建应用

安装所有工具后，创建一个新的 .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 命令仍然有用。

若要运行程序，请使用 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# 带来了声明性能力，但它们是一种元数据形式的代码，本身并不执行操作。