C#中的特性Attribute（转载）

转自：http://www.cnblogs.com/huqingyu/archive/2004/07/05/21459.html

原著：Sadaf Alvi           翻译：Abbey 原文出处 Attributes in C#， CodeProject

摘要
　　在这篇指南里，我们将会看到如何自己创建特性(Attribute)，并将其用到不同的程序实体(Entity)上，在程序运行时获取特性信息。

译注
　　由于Property 已被译作“属性”，就将 Attribute译作“特性”。

介绍
　　特性(Attribute)是一种新型的声明信息。我们可以使用特性来定义设计时的信息(比如帮助文件、文档的链接)，以及运行时的信息(比如将一个类的域与一个XML的域相关联)。我们也可以用特性来创建“自描述”的组件(可以提供该组件的描述信息)。在这篇指南里，我们将会看到如何自己创建特性(Attribute)，并将其用到不同的程序实体(Entity)上，并在程序运行时获取特性信息。

 特性的概念
　　MSDN(ms-help://MS.MSDNQTR.2002APR.1033/csspec/html/vclrfcsharpspec_17_2.htm)里是这样定义的：特性是一个声明的附加声明。

使用预定义的特性
　　C#已经预定义了一小组的特性供我们使用。在学习如何创建一个自定义的特性前，我们先通过一段代码来看看怎么使用这些预定义的特性吧。

 

using System;
public class AnyClass 
 {
    [Obsolete("别用Old这个老方法了，请用New方法", true)]
    static void Old( ) { }
    static void New( ) { }
    public static void Main( ) 
    {
        Old( );
    }
}     
 

　　在这个例子里我们使用了Obsolete(“陈旧的”)特性，它会将其所修饰的程序实体(类、方法、数据成员等)说明为已废弃不用的。第一个参数—一个字符串说明这个实体为何被废弃、由谁代替。实际上这个字符串的内容你想写什么都可以。第二个参数则告诉编译器将用户对此实体的调用视作一个编译错误。这个参数的缺省值为false，表示编译器仅将用户对其的调用视作警告。编译上面这段代码时，我们将会得到一个编译错误(译注：注意编译错误后附的提示了吗？)：

AnyClass.Old() is obsolete：“别用Old这个老方法了，请用New方法”

开发自定义的特性
　　现在开始开发我们自己的特性吧。这儿有一个小窍门：从C#定义的System.Attribute类派生我们的特性类(从抽象基类System.Attribute直接或间接地派生一个类，该派生类都是一个特性类。一个特性类的声明就定义了一种新的特性类型)，然后得到了这样一个声明：

using System;
public class HelpAttribute : Attribute
{
}

不管你相不相信，我们已经创建了一个自定义的特性。我们可以象这样用它修饰任何的类：

[Help()]
public class AnyClass
{
}

注意：
　　在特性类名与后缀Attribute间存在一个自动的编译转换。因此当我们用一个特性去修饰一个程序实体时，不需要给出Attribute这个后缀。编译器首先会在System.Attribute的所有派生类中进行匹配，如果没有找到匹配特性，它就将特性名加上Attribute后缀名后再进行匹配。　　
　　目前我们的这个特性还没什么用，让我们加点内容吧。在这个示例里，我们为自定义的特性类添加了一个数据特性Description(Property)，我们将在本文的最后演示如何在运行时查询这些信息。

using System;
public class HelpAttribute : Attribute
{
    public HelpAttribute(String Descrition_in)
  {
        this.description = Description_in;
    }
    protected String description;
    public String Description 
  {
        get 
      {
            return this.description;
                 
        }            
    }    
}


[Help("这是个什么也不做的类")]
public class AnyClass
{
}

定义/控制自定义特性的使用
　　AttributeUsage 类是另一个预定义的特性类，以帮助我们控制自定义特性的使用。亦即我们可以定义自定义类的特性。这个类描述了如何使用自定义的特性类。AttributeUsage有三个数据特性可用以修饰我们的自定义的特性：
　

ValidOn	定义了自定义特性在哪些程序实体上可被使用。这个可使用实体的列表可通过AttributeTargets枚举类型的OR操作进行设置
AllowMultiple	定义了是否可在同一个程序实体上同时使用多个特性进行修饰
Inherited	定义了自定义特性的修饰是否可由被修饰类的派生类继承

　　让我们做点具体的吧。我们将会用一个AttributeUsage特性修饰我们的特性类，以控制其作用范围：

using System;
[AttributeUsage(AttributeTargets.Class), AllowMultiple = false, Inherited = false ]
public class HelpAttribute : Attribute
{
    public HelpAttribute(String Description_in)
  {
        this.description = Description_in;
    }
    protected String description;
    public String Description
    {
        get 
      {
            return this.description;
        }            
    }    
}

　　先看看AttributeTargets.Class，说明了我们的Help特性只能用以修饰类，下面的这段代码将会导致一个编译错误(“特性Help不能用在这样的声明上，它只能用在类的声明上”)，因为我们用Help特性去修饰方法AnyMethod()了：

[Help("this is a do-nothing class")]
public class AnyClass
{
    [Help("this is a do-nothing method")]    //error
    public void AnyMethod()
    {
    }
} 

编译错误：

AnyClass.cs: Attribute ''Help'' is not valid on this declaration type. 
It is valid on ''class'' declarations only.

　　当然我们可以AttributeTargets.All来允许Help特性修饰任何类型的程序实体。AttributeTargets可能的值包括：

• Assembly,
• Module,
• Class,
• Struct,
• Enum,
• Constructor,
• Method,
• Property,
• Field,
• Event,
• Interface,
• Parameter,
• Delegate,
• All = Assembly | Module | Class | Struct | Enum | Constructor | Method | Property | Field | Event | Interface | Parameter | Delegate,
• ClassMembers = Class | Struct | Enum | Constructor | Method | Property | Field | Event | Delegate | Interface )

　　接下来，该看看AllowMultiple = false这句了：它确定了不能象下面这样，在同一实体上同时使用多个同种特性进行修饰：

[Help("this is a do-nothing class")]
[Help("it contains a do-nothing method")]
public class AnyClass
{
    [Help("this is a do-nothing method")]        //这也是错误的，因为Help特性只能修饰类
    public void AnyMethod()
    {
    }
}

编译错误：

      AnyClass.cs: Duplicate ''Help'' attribute

　　我们再来谈谈AttributeUsage的最后一个属性Inherited：定义了自定义特性的修饰是否可由被修饰类的派生类继承。基于下示代码表示的继承关系，让我们看看会发生什么吧：

[Help("BaseClass")] 
public class Base
{
}

public class Derive :  Base
{
}

我们选择了AttributeUsage的四种组合：

• [AttributeUsage(AttributeTargets.Class, AllowMultiple = false, Inherited = false ]
• [AttributeUsage(AttributeTargets.Class, AllowMultiple = true, Inherited = false ]
• [AttributeUsage(AttributeTargets.Class, AllowMultiple = false, Inherited = true ]
• [AttributeUsage(AttributeTargets.Class, AllowMultiple = true, Inherited = true ]

对应上述组合的结果：

1. 如果我们查询(稍后我们会看见如何在运行时查询一个类的特性信息。)这个Derive类的Help特性时，会因其未从基类继承该特性而一无所获。
2. 因为同样的原因，得到与结果一同样的结果。
3. 为了解释这后面的两种情况，我们把同样的特性也用在这个Derive派生类上，代码修改如下：
   [Help("BaseClass")] 
   public class Base
   {
   }
   
   [Help("DeriveClass")] 
   public class Derive :  Base
   {
   }
   
   我们的查询会同时得到其类Base与派生类Dervie的Help特性信息，因为继承与多重修饰均被允许。

注意：
　　AttributeUsage只能用于System.Attribute的派生类，且该派生类的AllowMultiple与Inherited都为false。

定位参数与命名参数 　　
　　定位参数是特性类构造函数(Constructor)的参数。它们是每次使用该特性修饰某个程序实体时都必须提供值的参数。相对的，命名参数则是可选参数，它也不是特性类构造函数的参数。为了详细解释它们的含义，让我们给Help特性类加点内容，然后看看下面的示例：

[AttributeUsage(AttributeTargets.Class, AllowMultiple = false, Inherited = false)]
public class HelpAttribute : Attribute
{
    public HelpAttribute(String Description_in)
    {
        this.description = Description_in;
        this.verion = "No Version is defined for this class";
    }
    protected String description;
    public String Description
    {
        get 
        {
            return this.description;
        }
    }
    protected String version;
    public String Version
    {
        get 
        {
            return this.version;
        }
        //即便我们不想我们的属性用户设置Version这个数据属性，我们也不得不提供set方法
        set 
        {
            this.verion = value;
        }
    }
}

[Help("This is Class1")]
public class Class1
{
}

[Help("This is Class2", Version = "1.0")]
public class Class2
{
}

[Help("This is Class3", Version = "2.0", 
 Description = "This is do-nothing class")]
public class Class3
{
}

我们查询Class1的Help特性信息时，会得到下列结果：

Help.Description : This is Class1
Help.Version :No Version is defined for this class

　　如果我们不定义Version属性的值，那么构造函数的函数体内所赋的缺省值将会使用。如果也没有，那么该属性对应的数据类型的缺省值将被使用(比如int类型的缺省值为0)。查询Class2将会得到这样的结果：

Help.Description : This is Class2
Help.Version :  1.0

　　请不要为了可选的参数而提供多个构造函数的重载版本，而应该将它们定义成命名参数。我们之所以称其为“命名的”，是我们为了能在构造函数里给它们赋值，不得不用一个个的标识符定义和访问它们。比如在第二个类中Help特性的使用[Help("This is Class2", Version = "1.0")] 你瞧，AttributeUsage的ValidOn参数就是一个定位参数，而Inherited与AllowMultiple则是命名参数。　　注意：在特性类的构造函数中给命名参数赋值，我们必须为它提供一个相应的set方法，否则会导致这样的编译错误(Version不能是一个只读的属性)：

''Version'' : Named attribute argument can''t be a read only property

　　当我们查询Class3的Help特性信息时会发生什么呢？会这样－因上述的原因导致编译错误(Description不能是只读的属性)：

''Desciption'' : Named attribute argument can''t be a read only property

所以还是给Description添加一个set方法吧。这样会得到正确的输出结果：

This is do-nothing class 
Help.Version : 2.0

　　这是因为构造函数利用定位参数构造一个特性时，它会调用所有命名参数的set方法。构造函数里的赋值行为实际均由各命名参数对应的属性的set方法完成，被其覆写(Override)了。

参数类型
　　一个特性类的参数可使用的数据类型限于：

• bool
• byte
• char
• double
• float
• int
• long
• short
• string
• System.Type
• object
• 枚举类型以及上述数据类型的一维数组

特性标识
　　让我们想象一下，怎么才能把我们的Help特性用到一个完整的程序集(assembly)上？首先要面对的问题是该把Help特性放在哪儿，以便让编译器识别出它是属于一个程序集的？再考虑另一种情况：我们想把一个特性用在某个方法的返回类型上时，编译器如何才能确定我们把它用在了返回类型而不是这个方法本身之上？要解决这么多含糊的问题，我们需要特性标识。借助特性标识的帮助，我们可以明确地告诉程序集我们希望把特性放在哪儿。比如：

[assembly: Help("this a do-nothing assembly")]

　　这个Help特性前的assembly标识符显式地告诉了编译器，当前这个Help特性用于整个程序集。可用的标识符包括：

• assembly
• module
• type
• method
• property
• event
• field
• param
• return

在运行时查询特性 　　
　　我们已经知道了如何创建特性并如何在程序中使用它们。现在该学习我们所建特性类的用户如何才能在运行时查询该特性类的信息了。要查询一个程序实体的所有特性信息，我们得使用反射(reflection)－在运行时发现类型信息的一种功能。
　　我们可以直接使用.NET Framework提供的反射Reflection API来枚举一个完整程序集的所有元数据(metadata)，并产生该程序集所有类、类型、方法的列表。还记得之前的Help特性和AnyClass类吗？

using System;
using System.Reflection;
using System.Diagnostics;


//attaching Help attribute to entire assembly
[assembly : Help("This Assembly demonstrates custom attributes creation and their run-time query.")]

//our custom attribute class
public class HelpAttribute : Attribute
{
    public HelpAttribute(String Description_in)
    {
        this.description = Description_in;
    }
    protected String description;
    public String Description
    {
        get 
        {
            return this.deescription;              
        }            
    }    
}

//attaching Help attribute to our AnyClass
[HelpString("This is a do-nothing Class.")]
public class AnyClass
{
//attaching Help attribute to our AnyMethod
    [Help("This is a do-nothing Method.")]
    public void AnyMethod()
    {
    }
//attaching Help attribute to our AnyInt Field
    [Help("This is any Integer.")]
    public int AnyInt;
}

class QueryApp
{
    public static void Main()
    {
    }
}

　　我们将在接下来的两节里在我们的Main方法里加入特性查询的代码。

查询程序集的特性 　　
　　在接下来的代码片段里，我们获取当前进程的名字，并使用Assembly类的LoadFrom方法装载程序集。然后我们使用GetCustomAttributes方法获取当前程序集的所有自定义特性。接下来的foreach语句又遍历所有的特性对象，并试着将这些特性转化为Help特性(使用as关键字进行转换，如果转换失败，将会返回一个空值而不是触发一个异常)。再后的一条语句是指如果转换成功，则显示Help特性的所有属性信息。

class QueryApp
{
    public static void Main()
    {
        HelpAttribute HelpAttr;

        //Querying Assembly Attributes
        String assemblyName;
        Process p = Process.GetCurrentProcess();
        assemblyName = p.ProcessName + ".exe";

        Assembly a = Assembly.LoadFrom(assemblyName);

        foreach (Attribute attr in a.GetCustomAttributes(true))
        {
            HelpAttr = attr as HelpAttribute;
            if (null != HelpAttr)
            {
                Console.WriteLine("Description of {0}: {1}", assemblyName,HelpAttr.Description);
            }
        }
    }
}

程序的输出结果：

Description of QueryAttribute.exe:
This Assembly demonstrates custom attributes creation and 
their run-time query.
Press any key to continue

查询类、方法和域的特性
　　在下面的代码片段里，和上面的代码不同的只是Main方法的第一条语句变成了：

Type type = typeof(AnyClass);

　　它使用typeof操作符返回AnyClass对应的Type对象。其余的代码也类似上述的代码，我想不需要再做解释了吧。要查询方法和域的特性，我们首先要获得当前类中所有方法和类，然后再用类似于查询类的特性的方法来查询与之对应的特性。

class QueryApp
{
    public static void Main()
    {

        Type type = typeof(AnyClass);
        HelpAttribute HelpAttr;


        //Querying Class Attributes
        foreach (Attribute attr in type.GetCustomAttributes(true))
        {
            HelpAttr = attr as HelpAttribute;
            if (null != HelpAttr)
            {
                Console.WriteLine("Description of AnyClass: {0}", 
                                  HelpAttr.Description);
            }
        }

        //Querying Class-Method Attributes  
        foreach(MethodInfo method in type.GetMethods())
        {
            foreach (Attribute attr in method.GetCustomAttributes(true))
            {
                HelpAttr = attr as HelpAttribute;
                if (null != HelpAttr)
                {
                    Console.WriteLine("Description of {0}: {1}", 
                                      method.Name, 
                                      HelpAttr.Description);
                }
            }
        }

        //Querying Class-Field (only public) Attributes
        foreach(FieldInfo field in type.GetFields())
        {
            foreach (Attribute attr in field.GetCustomAttributes(true))
            {
                HelpAttr= attr as HelpAttribute;
                if (null != HelpAttr)
                {
                    Console.WriteLine("Description of {0}: {1}",
                                      field.Name,HelpAttr.Description);
                }
            }
        }
    }
}

下面是程序输出：

Description of AnyClass:
This is a do-nothing Class.
Description of AnyMethod:
This is a do-nothing Method.
Description of AnyInt:
This is any Integer.
Press any key to continue

关于作者
Sadaf Alvi，卡拉奇大学的自然科学学士，主页http://www24.brinkster.com/salvee