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

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.

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

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

• Obtention d'informations sur l'appelant d'une méthode.

Rubriques connexes

Pour plus d'informations, consultez :

• Création d'attributs personnalisés (C# et Visual Basic)

• 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)

• Attributs courants (C# et Visual Basic)

• Informations relatives à l'appelant (C# et Visual Basic)

Voir aussi

Référence

Réflexion (C# et Visual Basic)

Concepts

Guide de programmation C#

Autres ressources

Guide de programmation Visual Basic

Extension des métadonnées à l'aide des attributs