Pisanie atrybutów niestandardowych

  • Artykuł

Aby zaprojektować atrybuty niestandardowe, nie musisz uczyć się wielu nowych pojęć. Jeśli znasz programowanie obiektowe i wiesz, jak projektować klasy, masz już większość potrzebnej wiedzy. Atrybuty niestandardowe to tradycyjne klasy, które pochodzą bezpośrednio lub pośrednio z System.Attribute klasy. Podobnie jak w przypadku tradycyjnych klas atrybuty niestandardowe zawierają metody, które przechowują i pobierają dane.

Podstawowe kroki prawidłowego projektowania niestandardowych klas atrybutów są następujące:

W tej sekcji opisano każdy z tych kroków i kończy się przykładem atrybutu niestandardowego.

Stosowanie atrybutuUsageAttribute

Deklaracja atrybutu niestandardowego zaczyna się od atrybutu System.AttributeUsageAttribute , który definiuje niektóre kluczowe cechy klasy atrybutów. Można na przykład określić, czy atrybut może być dziedziczony przez inne klasy, czy też elementy, do których można zastosować atrybut. Poniższy fragment kodu pokazuje, jak używać elementu AttributeUsageAttribute:

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

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

<AttributeUsage(AttributeTargets.All, Inherited:=False, AllowMultiple:=True)>
Public Class SomeClass
    Inherits Attribute
    '...
End Class

Element AttributeUsageAttribute ma trzy elementy członkowskie, które są ważne podczas tworzenia atrybutów niestandardowych: AttributeTargets, Inherited i AllowMultiple.

Element członkowski AttributeTargets

W poprzednim przykładzie określono, AttributeTargets.All wskazując, że ten atrybut można zastosować do wszystkich elementów programu. Alternatywnie można określić AttributeTargets.Class, wskazując, że atrybut można zastosować tylko do klasy lub AttributeTargets.Method, wskazując, że atrybut można zastosować tylko do metody. Wszystkie elementy programu można oznaczyć jako opis za pomocą atrybutu niestandardowego w ten sposób.

Można również przekazać wiele AttributeTargets wartości. Poniższy fragment kodu określa, że atrybut niestandardowy można zastosować do dowolnej klasy lub metody:

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

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

<AttributeUsage(AttributeTargets.Class Or AttributeTargets.Method)>
Public Class SomeOtherClass
    Inherits Attribute
    '...
End Class

Właściwość dziedziczona

Właściwość AttributeUsageAttribute.Inherited wskazuje, czy atrybut może być dziedziczony przez klasy, które pochodzą z klas, do których zastosowano atrybut. Ta właściwość przyjmuje flagę (domyślną true ) lub false . W poniższym przykładzie MyAttribute ma wartość truedomyślną Inherited , natomiast YourAttribute ma Inherited wartość false:

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

[AttributeUsage(AttributeTargets::Method, Inherited = false)]
public ref class YourAttribute : Attribute
{
    //...
};

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

[AttributeUsage(AttributeTargets.Method, Inherited = false)]
public class YourAttribute : Attribute
{
    //...
}

' This defaults to Inherited = true.
Public Class MyAttribute
    Inherits Attribute
    '...
End Class

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

Te dwa atrybuty są następnie stosowane do metody w klasie MyClassbazowej :

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

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

Public Class MeClass
    <MyAttribute>
    <YourAttribute>
    Public Overridable Sub MyMethod()
        '...
    End Sub
End Class

Na koniec klasa YourClass jest dziedziczona z klasy MyClassbazowej . Metoda MyMethod pokazuje MyAttribute , ale nie YourAttribute:

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

};

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

Public Class YourClass
    Inherits MeClass
    ' MyMethod will have MyAttribute but not YourAttribute.
    Public Overrides Sub MyMethod()
        '...
    End Sub

End Class

Właściwość AllowMultiple

Właściwość AttributeUsageAttribute.AllowMultiple wskazuje, czy na elemecie może istnieć wiele wystąpień atrybutu. Jeśli ustawiono wartość true, wiele wystąpień jest dozwolonych. Jeśli ustawiono wartość false (wartość domyślna), dozwolone jest tylko jedno wystąpienie.

W poniższym przykładzie ma wartość falsedomyślną AllowMultiple typu , a parametr YourAttribute ma wartość true: MyAttribute

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

[AttributeUsage(AttributeTargets::Method, AllowMultiple = true)]
public ref class YourAttribute : Attribute
{
};

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

[AttributeUsage(AttributeTargets.Method, AllowMultiple = true)]
public class YourAttribute : Attribute
{
}

' This defaults to AllowMultiple = false.
Public Class MyAttribute
    Inherits Attribute
End Class

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

Po zastosowaniu MyAttribute wielu wystąpień tych atrybutów tworzy błąd kompilatora. W poniższym przykładzie kodu pokazano prawidłowe użycie YourAttribute elementu i nieprawidłowe użycie elementu MyAttribute:

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

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

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

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

Public Class MyClass
    ' This produces an error.
    ' Duplicates are not allowed.
    <MyAttribute>
    <MyAttribute>
    Public Sub MyMethod()
        '...
    End Sub

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

Jeśli właściwość AllowMultiple i Inherited właściwość są ustawione na true, klasa dziedziczona z innej klasy może dziedziczyć atrybut i mieć inne wystąpienie tego samego atrybutu zastosowanego w tej samej klasie podrzędnej. Jeśli AllowMultiple ustawiono falsewartość , wartości wszystkich atrybutów w klasie nadrzędnej zostaną zastąpione przez nowe wystąpienia tego samego atrybutu w klasie podrzędnej.

Deklarowanie klasy atrybutów

Po zastosowaniu AttributeUsageAttributepolecenia rozpocznij definiowanie specyfiki atrybutu. Deklaracja klasy atrybutów wygląda podobnie do deklaracji tradycyjnej klasy, jak pokazano w poniższym kodzie:

[AttributeUsage(AttributeTargets::Method)]
public ref class MyAttribute : Attribute
{
    // . . .
};

[AttributeUsage(AttributeTargets.Method)]
public class MyAttribute : Attribute
{
    // . . .
}

<AttributeUsage(AttributeTargets.Method)>
Public Class MyAttribute
    Inherits Attribute
    ' . . .
End Class

Ta definicja atrybutu pokazuje następujące kwestie:

  • Klasy atrybutów muszą być zadeklarowane jako klasy publiczne.

  • Zgodnie z konwencją nazwa klasy atrybutów kończy się wyrazem Atrybut. Chociaż nie jest to wymagane, ta konwencja jest zalecana w celu zapewnienia czytelności. Po zastosowaniu atrybutu dołączenie wyrazu Atrybut jest opcjonalne.

  • Wszystkie klasy atrybutów muszą dziedziczyć bezpośrednio lub pośrednio z System.Attribute klasy.

  • W programie Microsoft Visual Basic wszystkie niestandardowe klasy atrybutów muszą mieć System.AttributeUsageAttribute atrybut .

Deklarowanie konstruktorów

Podobnie jak w przypadku tradycyjnych klas atrybuty są inicjowane za pomocą konstruktorów. Poniższy fragment kodu ilustruje typowy konstruktor atrybutu. Ten publiczny konstruktor przyjmuje parametr i ustawia zmienną składową równą jej wartości.

MyAttribute(bool myvalue)
{
    this->myvalue = myvalue;
}

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

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

Konstruktor można przeciążyć, aby uwzględnić różne kombinacje wartości. Jeśli zdefiniujesz również właściwość dla niestandardowej klasy atrybutów, podczas inicjowania atrybutu można użyć kombinacji nazwanych i pozycyjnych parametrów. Zazwyczaj wszystkie wymagane parametry są definiowane jako pozycyjne i wszystkie parametry opcjonalne jako nazwane. W takim przypadku nie można zainicjować atrybutu bez wymaganego parametru. Wszystkie inne parametry są opcjonalne.

Uwaga

W języku Visual Basic konstruktory klasy atrybutów nie powinny używać argumentu ParamArray .

Poniższy przykład kodu pokazuje, jak można zastosować atrybut używający poprzedniego konstruktora przy użyciu opcjonalnych i wymaganych parametrów. Przyjęto założenie, że atrybut ma jedną wymaganą wartość logiczną i jedną opcjonalną właściwość ciągu.

// One required (positional) and one optional (named) parameter are applied.
[MyAttribute(false, OptionalParameter = "optional data")]
public ref class SomeClass
{
    //...
};
// One required (positional) parameter is applied.
[MyAttribute(false)]
public ref class SomeOtherClass
{
    //...
};

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

' One required (positional) and one optional (named) parameter are applied.
<MyAttribute(false, OptionalParameter:="optional data")>
Public Class SomeClass
    '...
End Class

' One required (positional) parameter is applied.
<MyAttribute(false)>
Public Class SomeOtherClass
    '...
End Class

Deklarowanie właściwości

Jeśli chcesz zdefiniować nazwany parametr lub łatwo zwrócić wartości przechowywane przez atrybut, zadeklaruj właściwość. Właściwości atrybutu należy zadeklarować jako jednostki publiczne z opisem typu danych, który zostanie zwrócony. Zdefiniuj zmienną, która będzie przechowywać wartość właściwości i skojarzyć ją z metodami get i set . W poniższym przykładzie kodu pokazano, jak zaimplementować właściwość w atrybucie:

property bool MyProperty
{
    bool get() {return this->myvalue;}
    void set(bool value) {this->myvalue = value;}
}

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

Przykład atrybutu niestandardowego

Ta sekcja zawiera poprzednie informacje i pokazuje, jak zaprojektować atrybut, który dokumentuje informacje o autorze sekcji kodu. Atrybut w tym przykładzie przechowuje nazwę i poziom programisty oraz informację, czy kod został przejrzyszony. Używa trzech zmiennych prywatnych do przechowywania rzeczywistych wartości do zapisania. Każda zmienna jest reprezentowana przez właściwość publiczną, która pobiera i ustawia wartości. Na koniec konstruktor jest definiowany z dwoma wymaganymi parametrami:

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

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

    DeveloperAttribute(String^ name, String^ level)
    {
        this->name = name;
        this->level = level;
        this->reviewed = false;
    }

    // Define Name property.
    // This is a read-only attribute.

    virtual property String^ Name
    {
        String^ get() {return name;}
    }

    // Define Level property.
    // This is a read-only attribute.

    virtual property String^ Level
    {
        String^ get() {return level;}
    }

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

    virtual property bool Reviewed
    {
        bool get() {return reviewed;}
        void set(bool value) {reviewed = value;}
    }
};

[AttributeUsage(AttributeTargets.All)]
public class DeveloperAttribute : 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 Attribute
    ' Private fields.
    Private myname As String
    Private mylevel As String
    Private myreviewed As Boolean

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

    Public Sub New(name As String, level As String)
        Me.myname = name
        Me.mylevel = level
        Me.myreviewed = False
    End Sub

    ' Define Name property.
    ' This is a read-only attribute.

    Public Overridable ReadOnly Property Name() As String
        Get
            Return myname
        End Get
    End Property

    ' Define Level property.
    ' This is a read-only attribute.

    Public Overridable ReadOnly Property Level() As String
        Get
            Return mylevel
        End Get
    End Property

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

    Public Overridable Property Reviewed() As Boolean
        Get
            Return myreviewed
        End Get
        Set
            myreviewed = value
        End Set
    End Property
End Class

Ten atrybut można zastosować przy użyciu pełnej nazwy , DeveloperAttributelub przy użyciu skróconej nazwy , Developerw jeden z następujących sposobów:

[Developer("Joan Smith", "1")]

-or-

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

[Developer("Joan Smith", "1")]

-or-

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

<Developer("Joan Smith", "1")>

-or-

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

W pierwszym przykładzie pokazano atrybut zastosowany tylko z wymaganymi nazwanymi parametrami. W drugim przykładzie przedstawiono atrybut zastosowany zarówno z wymaganymi, jak i opcjonalnymi parametrami.

Zobacz też