Attributs (C#)Attributes (C#)

Les attributs fournissent une méthode puissante permettant d’associer des métadonnées ou des informations déclaratives avec du code (assemblys, types, méthodes, propriétés, etc.).Attributes provide a powerful method of associating metadata, or declarative information, with code (assemblies, types, methods, properties, and so forth). Une fois associé à une entité de programme, l’attribut peut être interrogé à l’exécution à l’aide d’une technique appelée réflexion.After an attribute is associated with a program entity, the attribute can be queried at run time by using a technique called reflection. Pour plus d’informations, consultez Réflexion (C#).For more information, see Reflection (C#).

Les attributs ont les propriétés suivantes :Attributes have the following properties:

  • Les attributs ajoutent des métadonnées à un programme.Attributes add metadata to your program. Les métadonnées sont des informations sur les types définis dans un programme.Metadata is information about the types defined in a program. Tous les assemblys .NET contiennent un ensemble spécifié de métadonnées qui décrivent les types et membres de types définis dans l’assembly.All .NET assemblies contain a specified set of metadata that describes the types and type members defined in the assembly. Vous pouvez ajouter des attributs personnalisés pour spécifier des informations supplémentaires si nécessaire.You can add custom attributes to specify any additional information that is required. Pour plus d’informations, consultez Création d’attributs personnalisés (C#).For more information, see, Creating Custom Attributes (C#).
  • Vous pouvez appliquer un ou plusieurs attributs à des modules ou des assemblys entiers ou à de plus petits éléments de programmes, comme des classes et des propriétés.You can apply one or more attributes to entire assemblies, modules, or smaller program elements such as classes and properties.
  • Les attributs peuvent accepter des arguments de la même façon que les méthodes et les propriétés.Attributes can accept arguments in the same way as methods and properties.
  • Votre programme peut examiner ses propres métadonnées ou celles d’autres programmes grâce à la réflexion.Your program can examine its own metadata or the metadata in other programs by using reflection. Pour plus d’informations, consultez Accès à des attributs à l’aide de la réflexion (C#).For more information, see Accessing Attributes by Using Reflection (C#).

Utilisation d’attributsUsing attributes

Les attributs peuvent être placés sur la quasi-totalité des déclarations, même si un attribut donné peut restreindre les types de déclarations sur lesquels il est valide.Attributes can be placed on most any declaration, though a specific attribute might restrict the types of declarations on which it is valid. En C#, vous spécifiez un attribut en plaçant son nom entre crochets ([]) au-dessus de la déclaration de l’entité à laquelle il s’applique.In C#, you specify an attribute by placing the name of the attribute enclosed in square brackets ([]) above the declaration of the entity to which it applies.

Dans cet exemple, l’attribut SerializableAttribute est utilisé pour appliquer une caractéristique spécifique à une classe :In this example, the SerializableAttribute attribute is used to apply a specific characteristic to a class:

[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 :A method with the attribute DllImportAttribute is declared like the following example:

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

Plusieurs attributs peuvent être placés dans une déclaration comme dans l’exemple suivant :More than one attribute can be placed on a declaration as the following example shows:

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) { }

Certains attributs peuvent être spécifiés plusieurs fois pour une entité donnée.Some attributes can be specified more than once for a given entity. ConditionalAttribute est un exemple d’attribut à utilisation multiple :An example of such a multiuse attribute is ConditionalAttribute:

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

Notes

Par convention, tous les noms d’attributs se terminent par le mot « Attribute » pour les différencier d’autres éléments dans les bibliothèques .NET.By convention, all attribute names end with the word "Attribute" to distinguish them from other items in the .NET libraries. Toutefois, il est inutile de spécifier le suffixe d’attribut lorsque les attributs sont utilisés dans le code.However, you do not need to specify the attribute suffix when using attributes in code. Par exemple, [DllImport] équivaut à [DllImportAttribute], mais DllImportAttribute est le nom réel de l’attribut dans la bibliothèque de classes .NET Framework.For example, [DllImport] is equivalent to [DllImportAttribute], but DllImportAttribute is the attribute's actual name in the .NET Framework Class Library.

Paramètres d’attributsAttribute parameters

Beaucoup d’attributs possèdent des paramètres. Ceux-ci peuvent être positionnels, sans nom ou nommés.Many attributes have parameters, which can be positional, unnamed, or named. Les paramètres positionnels doivent être spécifiés dans un certain ordre et ne peut pas être omis.Any positional parameters must be specified in a certain order and cannot be omitted. Les paramètres nommés sont facultatifs et peuvent être spécifiés dans n’importe quel ordre.Named parameters are optional and can be specified in any order. Les paramètres positionnels sont spécifiés en premier.Positional parameters are specified first. Par exemple, ces trois attributs sont équivalents :For example, these three attributes are equivalent:

[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 se place toujours en premier ; les autres sont nommés.The first parameter, the DLL name, is positional and always comes first; the others are named. Dans ce cas, les deux paramètres nommés ont la valeur false par défaut ; ainsi, ils peuvent être omis.In this case, both named parameters default to false, so they can be omitted. Les paramètres positionnels correspondent aux paramètres du constructeur d’attribut.Positional parameters correspond to the parameters of the attribute constructor. Les paramètres nommés ou facultatifs correspondent aux propriétés ou champs de l’attribut.Named or optional parameters correspond to either properties or fields of the attribute. Reportez-vous à la documentation de chaque attribut pour plus d’informations sur les valeurs des paramètres par défaut.Refer to the individual attribute's documentation for information on default parameter values.

Cibles d’attributAttribute targets

La cible d’un attribut est l’entité à laquelle s’applique l’attribut.The target of an attribute is the entity which the attribute applies to. Par exemple, un attribut peut s’appliquer à une classe, à une méthode particulière ou à un assembly entier.For example, an attribute may apply to a class, a particular method, or an entire assembly. Par défaut, un attribut s’applique à l’élément qu’il précède.By default, an attribute applies to the element that it precedes. Mais vous pouvez également identifier de manière explicite, par exemple, si un attribut s’applique à une méthode, à son paramètre ou à sa valeur renvoyée.But you can also explicitly identify, for example, whether an attribute is applied to a method, or to its parameter, or to its return value.

Pour identifier de manière explicite une cible d’attribut, utilisez la syntaxe suivante :To explicitly identify an attribute target, use the following syntax:

[target : attribute-list]

La liste des valeurs target possibles est présentée dans le tableau suivant.The list of possible target values is shown in the following table.

Valeur cibleTarget value S'applique àApplies to
assembly Assembly entierEntire assembly
module Module d’assembly actuelCurrent assembly module
field Champ dans une classe ou un structField in a class or a struct
event événementEvent
method Méthode ou accesseurs de propriété get et setMethod or get and set property accessors
param Paramètres de méthode ou paramètres d’accesseur de propriété setMethod parameters or set property accessor parameters
property PropertyProperty
return Valeur de retour d’une méthode, indexeur de propriété ou accesseur de propriété getReturn value of a method, property indexer, or get property accessor
type Struct, classe, interface, énumération ou déléguéStruct, class, interface, enum, or delegate

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.You would specify the field target value to apply an attribute to the backing field created for an auto-implemented property.

L’exemple suivant montre comment appliquer des attributs à des modules et assemblys.The following example shows how to apply attributes to assemblies and modules. Pour plus d’informations, consultez Attributs courants (C#).For more information, see Common Attributes (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#.The following example shows how to apply attributes to methods, method parameters, and method return values in C#.

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

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

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

Notes

Quelle que soit la cible sur laquelle ValidatedContract est défini comme étant valide, la cible return doit être spécifiée, même si ValidatedContract a été défini pour s’appliquer seulement aux valeurs de retour.Regardless of the targets on which ValidatedContract is defined to be valid, the return target has to be specified, even if ValidatedContract were defined to apply only to return values. En d’autres termes, le compilateur n’utilise pas les informations AttributeUsage pour résoudre les cibles d’attribut ambiguës.In other words, the compiler will not use AttributeUsage information to resolve ambiguous attribute targets. Pour plus d’informations, consultez AttributeUsage (C#).For more information, see AttributeUsage (C#).

Utilisations courantes des attributsCommon uses for attributes

La liste suivante comprend certaines des utilisations courantes des attributs dans le code :The following list includes a few of the common uses of attributes in code:

  • Marquer des méthodes avec l’attribut WebMethod dans les services web pour indiquer que la méthode doit pouvoir être appelée via le protocole SOAP.Marking methods using the WebMethod attribute in Web services to indicate that the method should be callable over the SOAP protocol. Pour plus d'informations, consultez WebMethodAttribute.For more information, see WebMethodAttribute.
  • Décrire comment marshaler les paramètres de méthode en cas d’interaction avec du code natif.Describing how to marshal method parameters when interoperating with native code. Pour plus d'informations, consultez MarshalAsAttribute.For more information, see MarshalAsAttribute.
  • Décrire les propriétés COM des classes, méthodes et interfaces.Describing the COM properties for classes, methods, and interfaces.
  • Appeler du code non managé à l’aide de la classe DllImportAttribute.Calling unmanaged code using the DllImportAttribute class.
  • Décrire un assembly : titre, version, description ou marque.Describing your assembly in terms of title, version, description, or trademark.
  • Décrire les membres d’une classe à sérialiser à des fins de persistance.Describing which members of a class to serialize for persistence.
  • Décrire le mappage entre les membres de classe et des nœuds XML à des fins de sérialisation XML.Describing how to map between class members and XML nodes for XML serialization.
  • Décrire les exigences de sécurité des méthodes.Describing the security requirements for methods.
  • Spécifier les caractéristiques employées pour appliquer la sécurité.Specifying characteristics used to enforce security.
  • Contrôler les optimisations par le compilateur juste-à-temps (JIT) pour que le code reste facile à déboguer.Controlling optimizations by the just-in-time (JIT) compiler so the code remains easy to debug.
  • Obtenir des informations sur l’appelant d’une méthode.Obtaining information about the caller to a method.

Pour plus d'informations, voir :For more information, see:

Voir aussiSee also