Partage via

Attributs

  • Article

Les attributs fournissent une méthode puissante d’association de métadonnées ou d’informations déclaratives, avec du code (assemblys, types, méthodes, propriétés, etc.). Une fois qu’un attribut est associé à une entité de programme, l’attribut peut être interrogé au moment de l’exécution à l’aide d’une technique appelée réflexion.

Les attributs ont les propriétés suivantes :

  • Les attributs ajoutent des métadonnées à votre programme. Les métadonnées sont des informations sur les types définis dans un programme. Tous les assemblys .NET contiennent un ensemble de métadonnées spécifié qui décrit les types et les membres de type définis dans l’assembly. Vous pouvez ajouter des attributs personnalisés pour spécifier toutes les informations supplémentaires requises.
  • Vous pouvez appliquer un ou plusieurs attributs à des assemblys, modules ou éléments de programme plus petits, tels que des classes et des propriétés.
  • Les attributs peuvent accepter des arguments de la même façon que les méthodes et les propriétés.
  • Votre programme peut examiner ses propres métadonnées ou les métadonnées d’autres programmes à l’aide de la réflexion.

Reflection fournit des objets (de type Type) qui décrivent des assemblies, des modules et des types. Vous pouvez utiliser la réflexion pour créer dynamiquement une instance d’un type, lier le type à un objet existant ou obtenir le type à partir d’un objet existant et appeler ses méthodes ou accéder à ses champs et propriétés. Si vous utilisez des attributs dans votre code, la réflexion vous permet d’y accéder. Pour plus d’informations, consultez Attributs.

Voici un exemple simple de réflexion à l’aide de la méthode GetType() ( héritée par tous les types de la classe de base Object ) pour obtenir le type d’une variable :

Remarque

Veillez à ajouter using System; et using System.Reflection; en haut de votre fichier .cs.

// Using GetType to obtain type information:
int i = 42;
Type type = i.GetType();
Console.WriteLine(type);

La sortie est la suivante : System.Int32.

L’exemple suivant utilise la réflexion pour obtenir le nom complet de l’assembly chargé.

// Using Reflection to get information of an Assembly:
Assembly info = typeof(int).Assembly;
Console.WriteLine(info);

La sortie est quelque chose comme : System.Private.CoreLib, Version=7.0.0.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798e.

Remarque

Les mots clés C# protected et internal n’ont aucune signification dans le langage intermédiaire (IL) et ne sont pas utilisés dans les API de réflexion. Les termes correspondants dans IL sont Famille et Assemblage. Pour identifier une méthode internal à l’aide de la réflexion, utilisez la propriété IsAssembly. Pour identifier une méthode protected internal, utilisez la IsFamilyOrAssembly.

Utilisation d’attributs

Les attributs peuvent être placés sur presque n’importe quelle déclaration, bien qu’un attribut spécifique puisse restreindre les types de déclarations sur lesquels il est valide. En C#, vous spécifiez un attribut en plaçant le nom de l’attribut entre crochets ([]) au-dessus de la déclaration de l’entité à laquelle elle s’applique.

Dans cet exemple, l’attribut SerializableAttribute est utilisé pour appliquer une caractéristique spécifique à une classe :

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

Une méthode avec l’attribut DllImportAttribute est déclarée comme dans l’exemple suivant :

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

Plusieurs attributs peuvent être placés sur une déclaration, comme l’illustre l’exemple suivant :

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

Certains attributs peuvent être spécifiés plusieurs fois pour une entité donnée. Un exemple de tel attribut multiutiliseur est ConditionalAttribute:

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

Remarque

Par convention, tous les noms d’attributs se terminent par le mot « Attribut » pour les distinguer des autres éléments des bibliothèques .NET. Toutefois, vous n’avez pas besoin de spécifier le suffixe d’attribut lors de l’utilisation d’attributs dans le code. Par exemple, [DllImport] équivaut à [DllImportAttribute], mais DllImportAttribute est le nom réel de l’attribut dans la bibliothèque de classes .NET.

Paramètres d’attribut

De nombreux attributs ont des paramètres, qui peuvent être positionnels, non nommés ou nommés. Tous les paramètres positionnels doivent être spécifiés dans un certain ordre et ne peuvent pas être omis. Les paramètres nommés sont facultatifs et peuvent être spécifiés dans n’importe quel ordre. Les paramètres positionnels sont spécifiés en premier. Par exemple, ces trois attributs sont équivalents :

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

Le premier paramètre, le nom de la DLL, est positionnel et vient toujours en premier ; les autres sont nommés. Dans ce cas, les deux paramètres nommés ont la valeur false par défaut, afin qu’ils puissent être omis. Les paramètres positionnels correspondent aux paramètres du constructeur d’attribut. Les paramètres nommés ou facultatifs correspondent aux propriétés ou champs de l’attribut. Reportez-vous à la documentation de l’attribut individuel pour plus d’informations sur les valeurs de paramètre par défaut.

Pour plus d’informations sur les types de paramètres autorisés, consultez la section Attributs de la spécification du langage C# .

Cibles d’attribut

La cible d’un attribut est l’entité à laquelle l’attribut s’applique. Par exemple, un attribut peut s’appliquer à une classe, à une méthode particulière ou à un assembly entier. Par défaut, un attribut s’applique à l’élément qui le suit. Toutefois, vous pouvez également identifier explicitement, par exemple, si un attribut est appliqué à une méthode, à son paramètre ou à sa valeur de retour.

Pour identifier explicitement une cible d’attribut, utilisez la syntaxe suivante :

[target : attribute-list]

La liste des valeurs target possibles est indiquée dans le tableau suivant.

Valeur cible S’applique à
assembly Ensemble entier
module Module d’assembly actuel
field Champ dans une classe ou une structure
event Événement
method Méthode ou accesseurs de propriété get et set
param Paramètres de méthode ou paramètres d’accesseur de propriété set
property Propriété
return Valeur de retour d’une méthode, d’un indexeur de propriétés ou d’un accesseur de propriété get
type Struct, classe, interface, énumération ou délégué

Vous devez spécifier la valeur cible de field pour appliquer un attribut au champ de stockage créé pour une propriété implémentée automatiquement.

L’exemple suivant montre comment appliquer des attributs à des assemblys et des modules. Pour plus d’informations, consultez Attributs communs (C#).

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

L’exemple suivant montre comment appliquer des attributs à des méthodes, des paramètres de méthode et des valeurs de retour de méthode en C#.

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

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

// applies to parameter
int Method3([ValidatedContract] string contract) { return 0; }

// applies to return value
[return: ValidatedContract]
int Method4() { return 0; }

Remarque

Quelles que soient les cibles sur lesquelles ValidatedContract est définie pour être valide, la cible return doit être spécifiée, même si ValidatedContract ont été définies pour s’appliquer uniquement aux valeurs de retour. En d’autres termes, le compilateur n'utilisera pas les informations de AttributeUsage pour résoudre les cibles ambiguës d’attribut. Pour plus d’informations, consultez AttributeUsage.

Utilisations courantes pour les attributs

La liste suivante inclut quelques-unes des utilisations courantes des attributs dans le code :

  • Marquage des méthodes à l’aide de l’attribut WebMethod dans les services Web pour indiquer que la méthode doit être appelante sur le protocole SOAP. Pour plus d’informations, consultez WebMethodAttribute.
  • Décrire comment marshaler les paramètres de méthode en cas d’interaction avec du code natif. Pour plus d’informations, consultez MarshalAsAttribute.
  • Description des propriétés COM pour les classes, méthodes et interfaces.
  • Appel de code non managé à l’aide de la classe DllImportAttribute.
  • Décrire votre assemblage en termes de titre, version, description ou marque commerciale.
  • Description des membres d’une classe à sérialiser pour la persistance.
  • Description de la façon de mapper entre les membres de classe et les nœuds XML pour la sérialisation XML.
  • Description des exigences de sécurité pour les méthodes.
  • Spécification des caractéristiques utilisées pour appliquer la sécurité.
  • Contrôler les optimisations par le compilateur juste-à-temps (JIT) pour que le code reste facile à déboguer.
  • Obtenir des informations sur l’appelant d’une méthode.

Vue d’ensemble de la réflexion

La réflexion est utile dans les situations suivantes :

Pour plus d’informations :