Attributs (C# et Visual Basic)
Les attributs fournissent une méthode performante pour associer des métadonnées, ou des informations de déclaration, au code (assemblies, types, méthodes, propriétés, etc.). Une fois qu'il est associé à une entité de programme, l'attribut peut être interrogé au moment de l'exécution au moyen d'une technique appelée réflexion. Pour plus d'informations, consultez Réflexion (C# et Visual Basic).
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 spécifique de métadonnées décrivant 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 nécessaires. Pour plus d'informations, consultez Création d'attributs personnalisés (C# et Visual Basic).
Vous pouvez appliquer un ou plusieurs attributs à des modules ou à des assemblys tout entiers, ou à des éléments de programme plus petits, comme les classes et les 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 celles dans d'autres programmes au moyen de la réflexion. Pour plus d'informations, consultez Accès à des attributs à l'aide de la réflexion (C# et Visual Basic).
Utilisation des attributs
Les attributs peuvent être placés dans la plupart des déclarations (même si un attribut particulier peut restreindre les types de déclaration dans lesquels il est valide). En C#, vous pouvez spécifier un attribut en plaçant son nom entre crochets ([]) au-dessus de la déclaration de l'entité à laquelle il s'applique. En Visual Basic, un attribut est placé entre les signes « inférieur à » et « supérieur à » (< >). Il doit figurer immédiatement avant l'élément auquel il s'applique, sur la même ligne.
Dans cet exemple, l'attribut SerializableAttribute est utilisé pour appliquer une caractéristique spécifique à une classe :
<System.Serializable()> Public Class SampleClass
' Objects of this type can be serialized.
End Class
[System.Serializable]
public class SampleClass
{
// Objects of this type can be serialized.
}
Une méthode utilisant l'attribut DllImportAttribute est déclarée de la manière suivante :
Imports System.Runtime.InteropServices
...
<System.Runtime.InteropServices.DllImport("user32.dll")>
Sub SampleMethod()
End Sub
using System.Runtime.InteropServices;
...
[System.Runtime.InteropServices.DllImport("user32.dll")]
extern static void SampleMethod();
Plusieurs attributs peuvent être placés dans une déclaration :
Imports System.Runtime.InteropServices
...
Sub MethodA(<[In](), Out()> ByVal x As Double)
End Sub
Sub MethodB(<Out(), [In]()> ByVal x As Double)
End Sub
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. ConditionalAttribute est un exemple d'attribut à usages multiples :
<Conditional("DEBUG"), Conditional("TEST1")>
Sub TraceMethod()
End Sub
[Conditional("DEBUG"), Conditional("TEST1")]
void TraceMethod()
{
// ...
}
Notes
Par convention, tous les noms d'attributs se terminent par le mot « Attribute » de façon à les distinguer des autres éléments du .NET Framework. Cependant, vous n'êtes pas obligé de spécifier le suffixe d'attribut lorsque vous employez des attributs dans le code. Par exemple, [DllImport] équivaut à [DllImportAttribute], mais DllImportAttribute est le véritable nom de l'attribut dans le .NET Framework.
Paramètres d'attribut
De nombreux attributs sont dotés de paramètres qui peuvent être positionnels, sans nom ou nommés. 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)]
<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. Dans ce cas, les paramètres nommés prennent par défaut la valeur false pour pouvoir être omis. Consultez la documentation des attributs individuels pour plus d'informations sur les valeurs par défaut des paramètres.
Cibles d'attribut
La cible d'un attribut est l'entité à laquelle il 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 qu'il précède. Toutefois, vous pouvez aussi identifier la cible de façon explicite en indiquant par exemple si un attribut s'applique à une méthode, à son paramètre ou à sa valeur de retour.
Pour identifier de façon explicite la cible d'un attribut, utilisez la syntaxe suivante :
[target : attribute-list]
<target : attribute-list>
La liste de valeurs target possibles est présentée dans le tableau suivant.
C# |
Visual Basic |
S'applique à |
|---|---|---|
assembly |
Assembly |
Assembly entier |
module |
Module |
Module d'assembly actuel (qui est différent d'un module Visual Basic) |
field |
Non pris en charge |
Champ dans une classe ou un struct |
event |
Non pris en charge |
Événement |
method |
Non pris en charge |
Méthode ou accesseurs de propriété get et set |
param |
Non pris en charge |
Paramètres de méthode ou paramètres d'accesseur de propriété set |
property |
Non pris en charge |
Propriété |
return |
Non pris en charge |
Valeur de retour d'une méthode, d'un indexeur de propriété ou d'un accesseur de propriété get |
type |
Non pris en charge |
Struct, class, interface, enum ou delegate |
L'exemple suivant indique comment appliquer des attributs aux assemblys et aux modules. Pour plus d'informations, consultez Attributs courants (C# et Visual Basic).
Imports System.Reflection
<Assembly: AssemblyTitleAttribute("Production assembly 4"),
Module: CLSCompliant(True)>
using System;
using System.Reflection;
[assembly: AssemblyTitleAttribute("Production assembly 4")]
[module: CLSCompliant(true)]
L'exemple suivant indique comment appliquer des attributs aux méthodes, ainsi qu'aux paramètres et aux valeurs de retour des méthodes en C#.
// default: applies to method
[SomeAttr]
int Method1() { return 0; }
// applies to method
[method: SomeAttr]
int Method2() { return 0; }
// applies to return value
[return: SomeAttr]
int Method3() { return 0; }
Notes
Indépendamment des cibles sur lesquelles SomeAttr est défini comme valide, la cible return doit être spécifiée, même si SomeAttr a été défini pour s'appliquer uniquement aux valeurs de retour. En d'autres termes, le compilateur n'utilise pas les informations relatives à AttributeUsage pour lever l'ambiguïté des cibles des attributs. Pour plus d'informations, consultez AttributeUsage (C# et Visual Basic).
Utilisations courantes des attributs
La liste suivante décrit certaines des utilisations courantes des attributs dans le code :
Marquer les méthodes à l'aide de l'attribut WebMethod des services Web pour indiquer qu'elles doivent pouvoir être appelées à l'aide du protocole SOAP. Pour plus d'informations, consultez WebMethodAttribute.
Décrire la manière dont il faut marshaler les paramètres de méthode en cas d'interopérabilité avec du code natif Pour plus d'informations, consultez MarshalAsAttribute.
Décrire des propriétés COM de classes, méthodes et interfaces
Appeler du code non managé à l'aide de la classe DllImportAttribute.
Décrire un assembly au moyen d'un titre, d'une version, d'une description ou d'une marque
Désigner des membres d'une classe à sérialiser en vue de leur persistance
Décrire comment mapper des membres de classe et des nœuds XML dans le cadre de la sérialisation XML
Définir les conditions requises en matière de sécurité des méthodes
Spécifier les caractéristiques employées pour appliquer la sécurité
Contrôler les optimisations à l'aide du compilateur JIT (Just-In-Time) pour que le code demeure facile à déboguer
Rubriques connexes
Pour plus d'informations, consultez :
Accès à des attributs à l'aide de la réflexion (C# et Visual Basic)
Comment : créer une union C/C++ à l'aide d'attributs (C# et Visual Basic)
Voir aussi
Référence
Réflexion (C# et Visual Basic)
Concepts
Extension des métadonnées à l'aide des attributs