特性

特性（C# - vs2010）

特性提供功能強大的方法，用以將元數據或聲明信息與代碼（程序集、類型、方法、屬性等）相關聯。 特性與程序實體關聯後，便可在運行時使用名爲「反射」的技術查詢特性。 有關更多信息，請參見 反射（C# 和 Visual Basic）。

特性具備如下屬性：

• 特性可向程序中添加元數據。 元數據是有關在程序中定義的類型的信息。 全部的 .NET 程序集都包含指定的一組元數據，這些元數據描述在程序集中定義的類型和類型成員。 能夠添加自定義特性，以指定所需的任何附加信息。 有關更多信息，請參見 建立自定義特性（C# 和 Visual Basic）。

• 能夠將一個或多個特性應用到整個程序集、模塊或較小的程序元素（如類和屬性）。

• 特性能夠與方法和屬性相同的方式接受參數。

• 程序可使用反射檢查本身的元數據或其餘程序內的元數據。 有關更多信息，請參見 使用反射訪問特性（C# 和 Visual Basic）。

使用特性

特性能夠放置在幾乎全部的聲明中（但特定的特性可能限制在其上有效的聲明類型）。 在 C# 中，特性的指定方法爲：將括在方括號中的特性名置於其應用到的實體的聲明上方。 在 Visual Basic 中，特性括在尖括號 (< >) 內。 它必須位於所應用於的元素的緊前面並與該元素在同一行。

在本例中，使用特性 SerializableAttribute 將特定特徵應用於類：

複製

[System.Serializable]
public class SampleClass
{
    // Objects of this type can be serialized.
}

具備 DllImportAttribute 特性的方法的聲明以下：

複製

using System.Runtime.InteropServices;

...

[System.Runtime.InteropServices.DllImport("user32.dll")]
extern static void SampleMethod();

一個聲明上可放置多個特性：

複製

using System.Runtime.InteropServices;

...

void MethodA([In][Out] ref double x) { }
void MethodB([Out][In] ref double x) { }
void MethodC([In, Out] ref double x) { }

某些特性對於給定實體能夠指定屢次。 例如，ConditionalAttribute 就是一個可屢次使用的特性：

複製

[Conditional("DEBUG"), Conditional("TEST1")]
void TraceMethod()
{
    // ...
}

注意
根據約定，全部特性名稱都以單詞「Attribute」結束，以便將它們與「.NET Framework」中的其餘項區分。 可是，在代碼中使用特性時，不須要指定 attribute 後綴。 例如，[DllImport] 雖等效於 [DllImportAttribute]，但 DllImportAttribute 纔是該特性在 .NET Framework 中的實際名稱。

特性參數

許多特性都有參數，而這些參數能夠是定位參數、未命名參數或命名參數。 任何定位參數都必須按特定順序指定而且不能省略，而命名參數是可選的且能夠按任意順序指定。 首先指定定位參數。 例如，這三個特性是等效的：

複製

[DllImport("user32.dll")]
[DllImport("user32.dll", SetLastError=false, ExactSpelling=false)]
[DllImport("user32.dll", ExactSpelling=false, SetLastError=false)]

第一個參數（DLL 名稱）是定位參數而且老是第一個出現，其餘參數爲命名參數。 在這種狀況下，兩個命名參數均默認爲 false，所以可將其省略。 有關默認參數值的信息，請參考各個特性的文檔。

特性目標

特性的目標是應用該特性的實體。 例如，特性能夠應用於類、特定方法或整個程序集。 默認狀況下，特性應用於它後面的元素。 可是，您也能夠顯式標識要將特性應用於方法仍是它的參數或返回值。

若要顯式標識特性目標，請使用下面的語法：

複製

[target : attribute-list]

下表顯示了可能的 target 值的列表。

C#	Visual Basic	適用對象
assembly	Assembly	整個程序集
module	Module	當前程序集模塊（不一樣於 Visual Basic 模塊）
field	不支持	在類或結構中的字段
event	不支持	event
method	不支持	方法或 get 和 set 屬性訪問器
param	不支持	方法參數或 set 屬性訪問器參數
property	不支持	Property
return	不支持	方法、屬性索引器或 get 屬性訪問器的返回值
type	不支持	結構、類、接口、枚舉或委託

下面的示例演示如何將特性應用於程序集和模塊。 有關更多信息，請參見 經常使用特性（C# 和 Visual Basic）。

複製

using System;
using System.Reflection;
[assembly: AssemblyTitleAttribute("Production assembly 4")]
[module: CLSCompliant(true)]

下面的示例演示如何在 C# 中將特性應用於方法、方法參數和方法返回值。

複製

// default: applies to method
[SomeAttr]
int Method1() { return 0; }

// applies to method
[method: SomeAttr]
int Method2() { return 0; }

// applies to return value
[return: SomeAttr]
int Method3() { return 0; }

注意
不管規定 SomeAttr 應用於什麼目標，都必須指定 return 目標，即便 SomeAttr 被定義爲僅應用於返回值也是如此。 換言之，編譯器將不使用 AttributeUsage 信息解析不明確的特性目標。 有關更多信息，請參見 AttributeUsage（C# 和 Visual Basic）。

特性的常見用途

如下列表包含特性的幾個常見用途：

• 在 Web 服務中，使用 WebMethod 特性來標記方法，以指示該方法應該可經過 SOAP 協議進行調用。 有關更多信息，請參見 WebMethodAttribute。

• 描述當與本機代碼進行交互操做時如何封送方法參數。 有關更多信息，請參見 MarshalAsAttribute。

• 描述類、方法和接口的 COM 屬性。

• 使用 DllImportAttribute 類調用非託管代碼。

• 在標題、版本、說明或商標方面描述您的程序集。

• 描述要持久性序列化類的哪些成員。

• 描述如何映射類成員和 XML 節點以便進行 XML 序列化。

• 描述方法的安全要求。

• 指定用於強制安全性的特性。

• 由實時 (JIT) 編譯器控制優化，以便易於調試代碼。

建立自定義特性

經過定義一個特性類，能夠建立您本身的自定義特性。該特性類直接或間接地從 Attribute 派生，有助於方便快捷地在元數據中標識特性定義。 假設您要用編寫類型的程序員的名字標記類型。 能夠定義一個自定義 Author 特性類：

複製

[System.AttributeUsage(System.AttributeTargets.Class |
                       System.AttributeTargets.Struct)
]
public class Author : System.Attribute
{
    private string name;
    public double version;

    public Author(string name)
    {
        this.name = name;
        version = 1.0;
    }
}

類名是特性的名稱，即 Author。 它由 System.Attribute 派生而來，所以是自定義特性類。 構造函數的參數是自定義特性的定位參數。 本示例中 name 是定位參數。 任何公共的讀寫字段或屬性都是命名參數。 在本例中，version 是惟一的命名參數。 請注意 AttributeUsage 特性的用法，它使得 Author 特性僅在類和 struct（在 Visual Basic 中是 Structure）聲明中有效。

能夠按以下所示使用此新特性：

複製

[Author("P. Ackerman", version = 1.1)]
class SampleClass
{
    // P. Ackerman's code goes here...
}

AttributeUsage 有一個命名參數 AllowMultiple，使用它可使自定義特性成爲一次性使用或可使用屢次的特性。 在下面的代碼示例中，建立了一個使用屢次的特性。

複製

[System.AttributeUsage(System.AttributeTargets.Class |
                       System.AttributeTargets.Struct,
                       AllowMultiple = true)  // multiuse attribute
]
public class Author : System.Attribute

在下面的代碼示例中，向某個類應用了同一類型的多個特性。

複製

[Author("P. Ackerman", version = 1.1)]
[Author("R. Koch", version = 1.2)]
class SampleClass
{
    // P. Ackerman's code goes here...
    // R. Koch's code goes here...
}

注意
若是特性類包含一個屬性，則該屬性必須爲讀寫屬性。

AttributeUsage

肯定能夠如何使用自定義特性類。 AttributeUsage 是一個可應用於自定義特性定義，以便控制如何應用新特性的特性。 顯式應用時默認設置以下所示：

複製

[System.AttributeUsage(System.AttributeTargets.All,
                   AllowMultiple = false,
                   Inherited = true)]
class NewAttribute : System.Attribute { }

在本例中，NewAttribute 類可應用於任何支持特性的代碼實體，可是對每一個實體只可應用一次。 當應用於基類時，它可由派生類繼承。

AllowMultiple 和 Inherited 參數是可選的，因此此代碼具備相同的效果：

複製

[System.AttributeUsage(System.AttributeTargets.All)]
class NewAttribute : System.Attribute { }

第一個 AttributeUsage 參數必須是 AttributeTargets 枚舉的一個或多個元素。 多個目標類型可以使用 OR 運算符連接在一塊兒，以下例所示：

複製

using System;

...

[AttributeUsage(AttributeTargets.Property | AttributeTargets.Field)]
class NewPropertyOrFieldAttribute : Attribute { }

若是 AllowMultiple 參數設置爲 true，則返回特性可對單個實體應用屢次，以下例所示：

複製

using System;

...

[AttributeUsage(AttributeTargets.Class, AllowMultiple = true)]
class MultiUseAttr : Attribute { }

[MultiUseAttr]
[MultiUseAttr]
class Class1 { }

[MultiUseAttr, MultiUseAttr]
class Class2 { }

在這種狀況下，因爲 AllowMultiple 設置爲 true，MultiUseAttr 可反覆應用。 所示的應用多個特性的這兩種格式均有效。

若是 Inherited 設置爲 false，則該特性不禁從特性化的類派生的類繼承。 例如：

複製

using System;

...

[AttributeUsage(AttributeTargets.Class, Inherited = false)]
class Attr1 : Attribute { }

[Attr1]
class BClass { }

class DClass : BClass { }

在這種狀況下，Attr1 不經過繼承應用於 DClass。

備註

AttributeUsage 特性是一個單用途特性，它沒法對相同的類應用屢次。 AttributeUsage 是 AttributeUsageAttribute 的別名。

有關更多信息，請參見 使用反射訪問特性（C# 和 Visual Basic）。

示例

下面的示例將闡釋 Inherited 參數和 AllowMultiple 參數對 AttributeUsage 特性的效果，以及如何才能枚舉應用於類的自定義特性。

複製

using System;

...

// Create some custom attributes:
[AttributeUsage(System.AttributeTargets.Class, Inherited = false)]
class A1 : System.Attribute { }

[AttributeUsage(System.AttributeTargets.Class)]
class A2 : System.Attribute { }

[AttributeUsage(System.AttributeTargets.Class, AllowMultiple = true)]
class A3 : System.Attribute { }

// Apply custom attributes to classes:
[A1, A2]
class BaseClass { }

[A3, A3]
class DerivedClass : BaseClass { }

public class TestAttributeUsage
{
    static void Main()
    {
        BaseClass b = new BaseClass();
        DerivedClass d = new DerivedClass();

        // Display custom attributes for each class.
        Console.WriteLine("Attributes on Base Class:");
        object[] attrs = b.GetType().GetCustomAttributes(true);
        foreach (Attribute attr in attrs)
        {
            Console.WriteLine(attr);
        }

        Console.WriteLine("Attributes on Derived Class:");
        attrs = d.GetType().GetCustomAttributes(true);
        foreach (Attribute attr in attrs)
        {
            Console.WriteLine(attr);
        }
    }
}

輸出

Attributes on Base Class:
A1
A2
Attributes on Derived Class:
A3
A3
A2

使用反射訪問特性

若是沒有檢索自定義特性的信息和對其進行操做的方法，則定義自定義特性並將其放置在源代碼中就沒有意義。 使用反射，可檢索用自定義特性定義的信息。 主要方法是 GetCustomAttributes，它返回對象數組，這些對象在運行時等效於源代碼特性。 此方法具備多個重載版本。 有關更多信息，請參見 Attribute。

特性規範，如：

複製

[Author("P. Ackerman", version = 1.1)]
class SampleClass

在概念上等效於：

複製

Author anonymousAuthorObject = new Author("P. Ackerman");
anonymousAuthorObject.version = 1.1;

可是，直到查詢 SampleClass 來獲取特性後纔會執行此代碼。 對 SampleClass 調用 GetCustomAttributes 會致使按上述方式構造並初始化一個 Author 對象。 若是該類具備其餘特性，則按類似的方式構造其餘特性對象。 而後 GetCustomAttributes 返回 Author 對象和數組中的任何其餘特性對象。 以後就能夠對此數組進行迭代，肯定根據每一個數組元素的類型所應用的特性，並從特性對象中提取信息。

示例

下面是一個完整的示例。 定義一個自定義特性，將其應用於若干實體並經過反射進行檢索。

複製

// Multiuse attribute.
[System.AttributeUsage(System.AttributeTargets.Class |
                       System.AttributeTargets.Struct,
                       AllowMultiple = true)  // Multiuse attribute.
]
public class Author : System.Attribute
{
    string name;
    public double version;

    public Author(string name)
    {
        this.name = name;

        // Default value.
        version = 1.0;
    }

    public string GetName()
    {
        return name;
    }
}

// Class with the Author attribute.
[Author("P. Ackerman")]
public class FirstClass
{
    // ...
}

// Class without the Author attribute.
public class SecondClass
{
    // ...
}

// Class with multiple Author attributes.
[Author("P. Ackerman"), Author("R. Koch", version = 2.0)]
public class ThirdClass
{
    // ...
}

class TestAuthorAttribute
{
    static void Test()
    {
        PrintAuthorInfo(typeof(FirstClass));
        PrintAuthorInfo(typeof(SecondClass));
        PrintAuthorInfo(typeof(ThirdClass));
    }

    private static void PrintAuthorInfo(System.Type t)
    {
        System.Console.WriteLine("Author information for {0}", t);

        // Using reflection.
        System.Attribute[] attrs = System.Attribute.GetCustomAttributes(t);  // Reflection.

        // Displaying output.
        foreach (System.Attribute attr in attrs)
        {
            if (attr is Author)
            {
                Author a = (Author)attr;
                System.Console.WriteLine("   {0}, version {1:f}", a.GetName(), a.version);
            }
        }
    }
}
/* Output:
    Author information for FirstClass
       P. Ackerman, version 1.00
    Author information for SecondClass
    Author information for ThirdClass
       R. Koch, version 2.00
       P. Ackerman, version 1.00
*/

如何：使用特性建立 C/C++ 聯合

經過使用特性能夠自定義結構在內存中的佈局方式。 例如，可使用 StructLayout(LayoutKind.Explicit) 和 FieldOffset 特性建立在 C/C++ 中稱爲聯合的佈局。

示例

在上一個代碼段中，TestUnion 的全部字段都從內存中的同一位置開始。

複製

[System.Runtime.InteropServices.StructLayout(LayoutKind.Explicit)]
struct TestUnion
{
    [System.Runtime.InteropServices.FieldOffset(0)]
    public int i;

    [System.Runtime.InteropServices.FieldOffset(0)]
    public double d;

    [System.Runtime.InteropServices.FieldOffset(0)]
    public char c;

    [System.Runtime.InteropServices.FieldOffset(0)]
    public byte b;
}

如下是字段從其餘顯式設置的位置開始的另外一個示例。

複製

[System.Runtime.InteropServices.StructLayout(LayoutKind.Explicit)]
struct TestExplicit
{
    [System.Runtime.InteropServices.FieldOffset(0)]
    public long lg;

    [System.Runtime.InteropServices.FieldOffset(0)]
    public int i1;

    [System.Runtime.InteropServices.FieldOffset(4)]
    public int i2;

    [System.Runtime.InteropServices.FieldOffset(8)]
    public double d;

    [System.Runtime.InteropServices.FieldOffset(12)]
    public char c;

    [System.Runtime.InteropServices.FieldOffset(14)]
    public byte b;
}

兩個整數字段 i1 和 i2 共享與 lg 相同的內存位置。 使用平臺調用時，這種結構佈局控制頗有用。

 

經常使用特性

全局特性

 

大多數特性適用於特定的語言元素，如類或方法；可是有些特性是全局的，它們適用於整個程序集或模塊。 例如，AssemblyVersionAttribute 特性可用於向程序集中嵌入版本信息，以下例所示：

複製

[assembly: AssemblyVersion("1.0.0.0")]

全局特性在源代碼中出如今任何頂級 using 指令（在 Visual Basic 中爲 Imports）以後、任何類型、模塊或命名空間聲明以前。 全局特性可顯示在多個源文件中，但這些文件必須在單一編譯傳遞中編譯。 對於 Visual Basic 項目，全局特性一般放在隨 Visual Basic 項目自動建立的 AssemblyInfo.vb 文件中。 在 C# 項目中，它們放在 AssemblyInfo.cs 文件中。

程序集特性是提供程序集相關信息的值。 它們分紅如下類別：

• 程序集標識特性

• 信息性特性

• 程序集清單特性

• 強名稱特性

程序集標識特性

三個特性（若是適用，還有強名稱）可肯定程序集的標識：名稱、版本和區域性。 這些特性構成程序集的完整名稱，在代碼中引用程序集時須要這些特性。 可使用特性來設置程序集的版本和區域性。 可是，名稱值由編譯器、「程序集信息」對話框中的 Visual Studio IDE 或程序集連接器 (Al.exe) 在建立程序集時根據包含程序集清單的文件進行設置。 AssemblyFlagsAttribute 特性指定程序集的多份副本是否能夠共存。

下表顯示標識特性：

特性	用途
AssemblyName	詳細描述程序集的標識。
AssemblyVersionAttribute	指定程序集的版本。
AssemblyCultureAttribute	指定程序集支持哪一個區域性。
AssemblyFlagsAttribute	指定程序集是否支持在同一臺計算機上、同一進程中或同一應用程序域中並行執行。

信息性特性

您可使用信息性特性爲程序集提供其餘的公司或產品信息。 下表顯示在 System.Reflection 命名空間中定義的信息性特性。

特性	用途
AssemblyProductAttribute	定義爲程序集清單指定產品名稱的自定義特性。
AssemblyTrademarkAttribute	定義爲程序集清單指定商標的自定義特性。
AssemblyInformationalVersionAttribute	定義爲程序集清單指定信息性版本的自定義特性。
AssemblyCompanyAttribute	定義爲程序集清單指定公司名稱的自定義特性。
AssemblyCopyrightAttribute	定義爲程序集清單指定版權的自定義特性。
AssemblyFileVersionAttribute	指示編譯器使用 Win32 文件版本資源的特定版本號。
CLSCompliantAttribute	指示程序集是否符合公共語言規範 (CLS)。

程序集清單特性

可使用程序集清單特性提供程序集清單中的信息。 其中包括標題、說明、默認別名和配置。 下表顯示在 System.Reflection 命名空間中定義的程序集清單特性。

特性	用途
AssemblyTitleAttribute	定義爲程序集清單指定程序集標題的自定義特性。
AssemblyDescriptionAttribute	定義爲程序集清單指定程序集說明的自定義特性。
AssemblyConfigurationAttribute	定義爲程序集清單指定程序集配置（如發佈或調試）的自定義特性。
AssemblyDefaultAliasAttribute	爲程序集清單定義友好默認別名

強名稱特性

在 Visual Studio 的早期版本中，使用強名稱對程序集進行簽名是使用如下程序集級特性執行的：

• AssemblyKeyFileAttribute

• AssemblyKeyNameAttribute

• AssemblyDelaySignAttribute

如今仍支持這樣作，可是給程序集簽名的首選方法是使用項目設計器中的「簽名頁」。 有關更多信息，請參見「項目設計器」->「簽名」頁和如何：對程序集進行簽名 (Visual Studio)。

已過期的特性

Obsolete 特性將某個程序實體標記爲一個建議再也不使用的實體。 每次使用被標記爲已過期的實體時，隨後將生成警告或錯誤，這取決於特性是如何配置的。 例如：

複製

[System.Obsolete("use class B")]
class A
{
    public void Method() { }
}
class B
{
    [System.Obsolete("use NewMethod", true)]
    public void OldMethod() { }
    public void NewMethod() { }
}

在此例中，Obsolete 特性應用於類 A 和方法 B.OldMethod。 由於應用於 B.OldMethod 的特性構造函數的第二個參數設置爲 true，因此此方法將致使編譯器錯誤，而使用類 A 只會產生警告。 可是，調用 B.NewMethod 既不產生警告也不產生錯誤。

向特性構造函數提供的做爲第一個參數的字符串將顯示爲警告或錯誤的一部分。 例如，當將它與前面的定義一塊兒使用時，下面的代碼將生成兩個警告和一個錯誤：

複製

// Generates 2 warnings:
// A a = new A();

// Generate no errors or warnings:
B b = new B();
b.NewMethod();

// Generates an error, terminating compilation:
// b.OldMethod();

爲類 A 產生兩個警告：一個用於聲明類引用，一個用於類構造函數。

可在不使用參數的狀況下使用 Obsolete 特性，但要包括此項已過期的緣由及改用什麼項的建議。

Obsolete 特性是一種單用途特性，而且可應用於容許特性的任何實體。 Obsolete 是 ObsoleteAttribute 的別名。

條件特性

Conditional 特性根據預處理標識符執行方法。 Conditional 特性是 ConditionalAttribute 的別名，可應用於方法或特性類。

在本示例中，Conditional 應用於方法以啓用或禁用程序特定的診斷信息的顯示：

複製

#define TRACE_ON
using System;
using System.Diagnostics;

public class Trace
{
    [Conditional("TRACE_ON")]
    public static void Msg(string msg)
    {
        Console.WriteLine(msg);
    }
}

public class ProgramClass
{
    static void Main()
    {
        Trace.Msg("Now in Main...");
        Console.WriteLine("Done.");
    }
}

若是未定義 TRACE_ON 標識符，則將不會顯示跟蹤輸出。

Conditional 特性常常與 DEBUG 標識符一塊兒使用以啓用調試版本的跟蹤和日誌記錄功能（在發行版本中沒有這兩種功能），以下例所示：

複製

[Conditional("DEBUG")]
static void DebugMethod()
{
}

當調用標記爲條件的方法時，指定的預處理符號的存在或不存在決定是否包含或省略此調用。 若是定義了該符號，則包含調用；不然省略調用。 使用 Conditional 是將方法包括在 #if…#endif 塊內的替代方法，它更整潔、更別緻，也減小了出錯的機會，以下例所示：

複製

#if DEBUG
    void ConditionalMethod()
    {
    }
#endif

條件方法必須是類或結構聲明中的方法，並且不能有返回值。

使用多個標識符

若是某個方法具備多個 Conditional 特性，且至少定義了其中一個條件符號（換言之，這些符號在邏輯上是使用 OR 運算符鏈接在一塊兒的），則將包含對該方法的調用。 在本例中，A 或 B 的存在將致使方法調用：

複製

[Conditional("A"), Conditional("B")]
static void DoIfAorB()
{
    // ...
}

若要使用 AND 運算符得到在邏輯上連接符號的效果，能夠定義序列條件方法。 例如，僅當 A 和 B 均已定義時，才能執行下面的第二種方法：

複製

[Conditional("A")]
static void DoIfA()
{
    DoIfAandB();
}

[Conditional("B")]
static void DoIfAandB()
{
    // Code to execute when both A and B are defined...
}

使用具備特性類的條件

還可將 Conditional 特性應用於特性類定義。 在本例中，僅當定義了 DEBUG 時，自定義特性 Documentation 才向元數據添加信息。

複製

[Conditional("DEBUG")]
public class Documentation : System.Attribute
{
    string text;

    public Documentation(string text)
    {
        this.text = text;
    }
}

class SampleClass
{
    // This attribute will only be included if DEBUG is defined.
    [Documentation("This method displays an integer.")]
    static void DoWork(int i)
    {
        System.Console.WriteLine(i.ToString());
    }
}