撰寫自訂屬性

發行項
08/21/2008

更新：2007 年 11 月

若要設計您自己的自訂屬性，您不需精通許多新概念。如果您熟悉物件導向程式設計並知道如何設計類別，您已經具備大部分所需的知識。自訂屬性基本上是直接或間接衍生自 System.Attribute 的傳統類別。就像傳統的類別，自訂屬性包含儲存和擷取資料的方法。

正確設計自訂屬性類別的主要步驟如下：

套用 AttributeUsageAttribute
宣告屬性類別
宣告建構函式
宣告屬性

這個章節描述這些各個步驟並以自訂屬性範例作結束。

套用 AttributeUsageAttribute

自訂屬性宣告以 AttributeUsageAttribute 開頭，來定義您屬性類別的某些關鍵特性。例如，您可以指定是否您的屬性可以被其他類別繼承，或指定屬性可以套用到哪些項目。下列程式碼片段示範如何使用 AttributeUsageAttribute。

[AttributeUsage(AttributeTargets.All, Inherited = false, AllowMultiple = true)]

<AttributeUsage(AttributeTargets.All, Inherited := False, AllowMultiple := true)>

System.AttributeUsageAttribute 有三個成員，對於建立自訂屬性非常重要：AttributeTargets、Inherited 及 AllowMultiple。

AttributeTargets 成員

前面範例中指定了 AttributeTargets.All，指示這個屬性可以套用到所有程式項目。或者，您可以指定 AttributeTargets.Class，表示您的屬性只能套用至類別，或是指定 AttributeTargets.Method，表示您的屬性只能套用至方法。所有程式項目都可以用這個方式使用自訂屬性來標示為描述。

您也可以傳遞多個 AttributeTargets 的執行個體。下列程式碼片段指定自訂屬性可以套用至任何類別或方法。

[AttributeUsage (AttributeTargets.Class | AttributeTargets.Method)]

<AttributeUsage (AttributeTargets.Class Or AttributeTargets.Method)>

Inherited 屬性

Inherited 屬性指示您的屬性是否可以被類別 (衍生自套用您屬性的類別) 所繼承。這個屬性接受 true (預設值) 或 false 旗標。例如，下列程式碼範例中，MyAttribute 有預設值為 true 的 Inherited 值，而 YourAttribute 則有為 false 的 Inherited 值。

//This defaults to Inherited = true.
public class MyAttribute :Attribute
{
}

[AttributeUsage( Inherited = false)]
public class YourAttribute : Attribute
{
}

<AttributeUsage( AttributeTargets.All, Inherited := True)> Public Class _
MyAttribute
    Inherits Attribute
End Class

<AttributeUsage( AttributeTargets.All, Inherited := False)> Public Class _
YourAttribute
    Inherits Attribute
End Class

接著套用兩個屬性至基底類別 MyClass 中的方法。

public class MyClass
{
    [MyAttribute]
    [YourAttribute]
    public virtual void MyMethod() 
    {
        //...
    }
}

' In Microsoft Visual Basic, you apply multiple attributes
' by separating them with commas.
Public Class [MyClass]
    <MyAttribute, YourAttribute> Public Overridable Sub MyMethod()
        '...
    End Sub
End Class

最後，類別 YourClass 繼承自基底類別 MyClass。方法 MyMethod 會顯示 MyAttribute，但不顯示 YourAttribute。

public class YourClass: MyClass
{
      //MyMethod will have MyAttribute but not YourAttribute.
      public override void MyMethod()
      {
         //...
      }

}

Public Class YourClass
   Inherits [MyClass]
      'MyMethod will have MyAttribute but not YourAttribute.
      Public overrides Sub MyMethod()
         '...
      End Sub
End Class

AllowMultiple 屬性

AllowMultiple 屬性指示您屬性的多個執行個體是否可以在項目上存在。如果設定成 true，允許多個執行個體存在；如果設定為 false (預設值)，則只允許有一個執行個體。

下列程式碼範例中，MyAttribute 有預設為 false 的 AllowMultiple 值，而 YourAttribute 有 true 值。

//This defaults to AllowMultiple = false.
public class MyAttribute :Attribute
{
}

[AttributeUsage(AllowMultiple = true)]
public class YourAttribute : Attribute
{
}

'This defaults to AllowMultiple = false.
<AttributeUsage(AttributeTargets.Method)> Public Class _
MyAttribute
    Inherits Attribute
End Class

<AttributeUsage(AttributeTargets.Method, AllowMultiple := True)> Public Class _
YourAttribute
    Inherits Attribute
End Class

套用這些屬性的多個執行個體時，MyAttribute 產生編譯器錯誤。下列程式碼範例示範 YourAttribute 的有效用法和 MyAttribute 的無效用法。

public class MyClass
{
    //This produces an error.
    //Duplicates are not allowed.
    [MyAttribute]
    [MyAttribute]
    public void MyMethod() {
        //...
    }

    //This is valid.
    [YourAttribute]
    [YourAttribute]
    public void YourMethod(){
    //...
    }
}

' In Microsoft Visual Basic you apply multiple attributes
' by separating them with commas.
Public Class [MyClass]
    'This produces an error.
    'Duplicates are not allowed.
    <MyAttribute, MyAttribute> Public Overridable Sub MyMethod()
        '...
    End Sub

    'This is valid.    
    <YourAttribute, YourAttribute> Public Sub YourMethod()
        '...
    End Sub
End Class

如果 AllowMultiple 屬性和 Inherited 屬性都設成 true，繼承另一個類別的類別可以繼承屬性，並且使得相同屬性的執行個體套用於相同子類別中。如果 AllowMultiple 設定為 false，父類別中的任何屬性值將被子類別中相同屬性的任何新執行個體覆寫。

宣告屬性類別

套用 AttributeUsageAttribute 之後，就可以開始定義屬性的細節。屬性類別的宣告看起來類似傳統類別的宣告，如下列程式碼所示範。

public class MyAttribute : System.Attribute 
{
    // . . . 
}

' This attribute is only usable with methods
<AttributeUsage(AttributeTargets.Method)> Public Class MyAttribute
    Inherits System.Attribute
    ' . . . 
End Class

這個屬性的定義顯示下列要點：

屬性類別必須宣告為公用 (Public) 類別。
根據慣例，屬性類別的名稱以 Attribute 做為結尾。即使沒有必要，仍建議使用此慣例以提高可讀性。套用屬性時，文字結尾的 Attribute 是選擇性的。
所有屬性類別必須直接或間接繼承自 System.Attribute。
在 Microsoft Visual Basic 中，所有自訂屬性類別都必須具有 AttributeUsageAttribute 屬性。

宣告建構函式

屬性以傳統類別的相同方式使用建構函式來初始化。下列程式碼片段說明一般屬性建構函式。這個公用建構函式具有一個參數並設定它的值等於成員變數。

public MyAttribute(bool myvalue)
{
    this.myvalue = myvalue;        
}

Public Sub New(newvalue As Boolean)
    Me.myvalue = newvalue
End Sub

您可以多載建構函式以容納不同組合的值。如果您也定義您自訂屬性類別的屬性，您可以在初始化屬性時，使用指名和位置參數的組合。基本上，您定義所有必要參數為位置參數，和所有選擇性參數為具名參數。在這個狀況中，不能不使用必要參數來初始化屬性。所有其他屬性為選擇性的。請注意，在 Visual Basic 中，屬性類別的建構函式不能使用 ParamArray 引數。

下列程式碼範例示範如何使用選擇性和必要參數，來套用使用先前建構函式的屬性。它假設屬性有一個必要的布林 (Boolean) 值和一個選擇性字串屬性。

//One required (positional) and one optional (named) parameter are applied.
[MyAttribute(false, OptionalParameter = "optional data")]
//One required (positional) parameter is applied.
[MyAttribute(false)]

'One required (positional) and one optional (named) parameter are applied.
<MyAttribute(False, OptionalParameter := "optional data")>
' ...
'One required (positional) parameter is applied.
<MyAttribute(False)>

宣告屬性

如果您想要定義具名參數，或是提供容易的方式來傳回屬性所儲存的值，請宣告屬性。屬性 (Attribute) 的屬性 (Property) 應該以將要傳回的資料型別描述宣告為公用實體 (Entity)。定義保留您屬性值的變數並將它與 get 和 set 方法關聯。下列程式碼範例示範如何在您的屬性中實作簡單屬性。

public bool MyProperty
{
    get {return this.myvalue;}
    set {this.myvalue = value;}
}

Public Property MyProperty As Boolean
    Get
        Return Me.myvalue
    End Get
    Set
        Me.myvalue = value
    End Set
End Property

自訂屬性範例

這個章節結合前面資訊，並示範如何設計簡單屬性以記錄有關一段程式碼作者的資訊。這個範例中的屬性儲存程式設計人員的名稱和等級，以及是否已經檢閱程式碼。它使用三個私用 (Private) 變數來存放要儲存的實際值。每一個變數由取得和設定數值的公用屬性來代表。最後，以兩個必要參數定義建構函式。

[AttributeUsage(AttributeTargets.All)]
public class DeveloperAttribute : System.Attribute 
{
        
    //Private fields.
    private string name;
    private string level;
    private bool reviewed;

    //This constructor defines two required parameters: name and level.

    public  DeveloperAttribute(string name,string level)
    {
        this.name = name;
        this.level = level; 
        this.reviewed = false;
    }

    //Define Name property.
    //This is a read-only attribute.
        
    public virtual string Name
    {
        get {return name;}        
    }

    //Define Level property.
    //This is a read-only attribute.
        
    public virtual string Level
    {
        get {return level;}
    }

    //Define Reviewed property. 
    //This is a read/write attribute. 

    public virtual bool Reviewed
    {
        get {return reviewed;}
    set {reviewed = value;}
    }
}

<AttributeUsage(AttributeTargets.All)> Public Class DeveloperAttribute
    Inherits System.Attribute
    
    'Private fields.
    Private m_name As String
    Private m_level As String
    Private m_reviewed As Boolean    
    
    'This constructor defines two required parameters: name and level.
    Public Sub New(name As String, level As String)
        Me.m_name = name
        Me.m_level = level
        Me.m_reviewed = False
    End Sub
    
    'Define Name property.
    'This is a read-only attribute.    
    Public Overridable ReadOnly Property Name() As String
        Get
            Return m_name
        End Get
    End Property 
    
    'Define Level property.
    'This is a read-only attribute.    
    Public Overridable ReadOnly Property Level() As String
        Get
            Return m_level
        End Get
    End Property
    
    'Define Reviewed property. 
    'This is a read/write attribute.    
    Public Overridable Property Reviewed() As Boolean
        Get
            Return m_reviewed
        End Get
        Set
            m_reviewed = value
        End Set
    End Property
End Class

您可以使用完整名稱 DeveloperAttribute，或使用縮寫名稱 Developer，以下列其中一種方式來套用這個屬性。

[Developer("Joan Smith", "1")]
[Developer("Joan Smith", "1", Reviewed = true)]

<Developer("Joan Smith", "1")>
<Developer("Joan Smith", "1", Reviewed := True)>

第一個範例示範只以必要指名參數套用的屬性，而第二範例則示範以必要和選擇性參數兩者都套用的屬性。

請參閱

參考

System.Attribute

AttributeUsageAttribute

其他資源

使用屬性擴充中繼資料

共用方式為

撰寫自訂屬性

套用 AttributeUsageAttribute

AttributeTargets 成員

Inherited 屬性

AllowMultiple 屬性

宣告屬性類別

宣告建構函式

宣告屬性

自訂屬性範例

請參閱

參考

其他資源

其他資源