Lire en anglais

Partager via


Utiliser des attributs personnalisés

Pour concevoir des attributs personnalisés, vous n’avez pas besoin d’apprendre beaucoup de nouveaux concepts. Si vous êtes familiarisé avec la programmation orientée objet et savez concevoir des classes, vous possédez déjà la plupart des connaissances nécessaires. Les attributs personnalisés sont des classes traditionnelles qui dérivent directement ou indirectement de la classe System.Attribute. Tout comme les classes traditionnelles, les attributs personnalisés contiennent des méthodes qui stockent et récupèrent les données.

Les principales étapes permettant de concevoir correctement des classes d’attributs personnalisés sont les suivantes :

Cette section décrit chacune de ces étapes et se termine par un exemple d’attribut personnalisé.

Application d’AttributeUsageAttribute

Une déclaration d’attribut personnalisé commence par l’attribut System.AttributeUsageAttribute, qui définit certaines caractéristiques clés de votre classe d’attributs. Par exemple, vous pouvez spécifier si votre attribut peut être hérité par d’autres classes ou les éléments auxquels l’attribut peut être appliqué. Le fragment de code suivant montre comment utiliser l’attribut AttributeUsageAttribute :

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

AttributeUsageAttribute possède trois membres importants pour la création d’attributs personnalisés : AttributeTargets, Inheritedet AllowMultiple.

Membre AttributeTargets

Dans l’exemple précédent, AttributeTargets.All est spécifié, ce qui indique que cet attribut peut être appliqué à tous les éléments de programme. Vous pouvez également spécifier AttributeTargets.Class, qui indique que votre attribut peut être appliqué uniquement à une classe, ou AttributeTargets.Method, qui indique que votre attribut peut être appliqué uniquement à une méthode. Tous les éléments de programme peuvent être marqués pour description par un attribut personnalisé de cette manière.

Vous pouvez également transmettre plusieurs valeurs de AttributeTargets. Le fragment de code suivant spécifie qu’un attribut personnalisé peut être appliqué à n’importe quelle classe ou méthode :

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

Propriété Inherited

La propriété AttributeUsageAttribute.Inherited indique si votre attribut peut être hérité par les classes qui sont dérivées des classes auxquelles votre attribut est appliqué. Cette propriété reçoit un indicateur true (par défaut) ou false. Dans l’exemple suivant, MyAttribute affiche une valeur par défaut Inherited de true, tandis YourAttribute affiche une valeur Inherited de false :

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

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

Les deux attributs sont ensuite appliqués à une méthode dans la classe de base MyClass :

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

Enfin, la classe YourClass est héritée de la classe de base MyClass. La méthode MyMethod affiche MyAttribute, mais pas YourAttribute :

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

Propriété AllowMultiple

La propriété AttributeUsageAttribute.AllowMultiple indique si plusieurs instances de votre attribut peuvent exister sur un élément. Si la valeur est true, plusieurs instances sont autorisées. Si elle est définie sur false (valeur par défaut), une seule instance est autorisée.

Dans l’exemple suivant, MyAttribute affiche une valeur par défaut AllowMultiple de false, tandis YourAttribute affiche une valeur de true :

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

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

Quand plusieurs instances de ces attributs sont appliquées, MyAttribute génère une erreur du compilateur. L’exemple de code suivant illustre l’utilisation valide de YourAttribute et l’utilisation non valide de 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()
    {
        //...
    }
}

Si la propriété AllowMultiple et la propriété Inherited ont la valeur true, une classe héritée d’une autre classe peut hériter d’un attribut et avoir une autre instance du même attribut appliquée dans la même classe enfant. Si AllowMultiple a la valeur false, les valeurs des attributs de la classe parente sont remplacées par les nouvelles instances du même attribut dans la classe enfant.

Déclaration de la classe d’attributs

Après avoir appliqué AttributeUsageAttribute, commencez à définir les spécificités de votre attribut. La déclaration d’une classe d’attributs ressemble à la déclaration d’une classe traditionnelle, comme illustré dans le code suivant :

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

Cette définition de l’attribut illustre les points suivants :

  • Les classes d’attributs doivent être déclarées comme des classes publiques.

  • Par convention, le nom de la classe d’attributs se termine par le mot Attribute. Même si elle n’est pas obligatoire, cette convention est recommandée pour une meilleure lisibilité. Quand l’attribut est appliqué, l’inclusion du mot Attribute est facultative.

  • Toutes les classes d’attributs doivent hériter directement ou indirectement de la classe System.Attribute.

  • Dans Microsoft Visual Basic, toutes les classes d’attributs personnalisés doivent avoir l’attribut System.AttributeUsageAttribute.

Déclaration des constructeurs

Tout comme les classes traditionnelles, les attributs sont initialisés avec des constructeurs. Le fragment de code suivant illustre un constructeur d’attribut classique. Ce constructeur public accepte un paramètre et définit une variable membre égale à sa valeur.

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

Vous pouvez surcharger le constructeur pour qu’il reçoive différentes combinaisons de valeurs. Si vous définissez également une propriété pour votre classe d’attributs personnalisés, vous pouvez utiliser une combinaison de paramètres nommés et positionnels lors de l’initialisation de l’attribut. En général, vous définissez tous les paramètres obligatoires comme des paramètres positionnels et tous les paramètres facultatifs comme des paramètres nommés. Dans ce cas, l’attribut ne peut pas être initialisé sans le paramètre obligatoire. Tous les autres paramètres sont facultatifs.

Notes

Dans Visual Basic, les constructeurs d’une classe d’attributs ne doivent pas utiliser d’argument ParamArray.

L’exemple de code suivant montre comment un attribut qui utilise le constructeur précédent peut être appliqué à l’aide de paramètres obligatoires et facultatifs. Il suppose que l’attribut a une valeur booléenne obligatoire et une propriété de chaîne facultative.

// 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
{
    //...
}

Déclaration des propriétés

Si vous voulez définir un paramètre nommé ou fournir un moyen facile de retourner les valeurs stockées par votre attribut, déclarez une propriété. Les propriétés d’attribut doivent être déclarées comme des entités publiques avec une description du type de données à retourner. Définissez la variable qui contient la valeur de votre propriété et associez-la aux méthodes get et set. L’exemple de code suivant montre comment implémenter une propriété dans votre attribut :

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

exemple d’attribut personnalisé

Cette section intègre les informations précédentes et montre comment concevoir un attribut qui documente des informations sur l’auteur d’une section de code. L’attribut de cet exemple stocke le nom et le niveau du programmeur, et indique si le code a été révisé. Il utilise trois variables privées pour stocker les valeurs réelles à enregistrer. Chaque variable est représentée par une propriété publique qui obtient et définit les valeurs. Enfin, le constructeur est défini avec deux paramètres obligatoires :

[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;}
    }
}

Vous pouvez appliquer cet attribut à l’aide du nom complet, DeveloperAttribute, ou à l’aide du nom abrégé, Developer, de l’une des manières suivantes :

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

-or-

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

Le premier exemple montre l’attribut appliqué uniquement avec les paramètres nommés requis. Le deuxième exemple montre l’attribut appliqué avec les paramètres obligatoires et facultatifs.

Voir aussi