Attributs courants (C# et Visual Basic)
Cette rubrique décrit les attributs les plus utilisés dans les programmes C# et Visual Basic.
Attributs globaux
Attribut obsolète
Attribut conditionnel
Attributs des informations de l'appelant
Attributs Visual Basic
Attributs globaux
La plupart des attributs s'appliquent à des éléments de langage spécifiques, tels que les classes ou les méthodes ; cependant, certains attributs sont globaux — ils s'appliquent à un assembly ou à un module entier. Par exemple, l'attribut AssemblyVersionAttribute peut être utilisé pour incorporer des informations de version dans un assembly, de la manière suivante :
[assembly: AssemblyVersion("1.0.0.0")]
<Assembly: AssemblyVersion("1.0.0.0")>
Les attributs globaux apparaissent dans le code source après les directives using de niveau supérieur (Imports en Visual Basic), et avant les déclarations de type, de module ou d'espace de noms. Les attributs globaux peuvent apparaître dans plusieurs fichiers sources, mais les fichiers doivent être compilés en un seul passage. Pour les projets Visual Basic, les attributs globaux sont généralement placés dans le fichier AssemblyInfo.vb, qui est créé automatiquement avec les projets Visual Basic. Dans les projets C#, ils sont placés dans le fichier AssemblyInfo.cs.
Les attributs d'assembly sont des valeurs qui fournissent des informations au sujet d'un assembly. Ils peuvent être répartis dans les catégories suivantes :
attributs d'identité d'assembly ;
attributs d'informations ;
attributs de manifeste d'assembly ;
attributs de nom fort ;
attributs d'identité d'assembly.
Trois attributs (associés à un nom fort s'il est applicable) déterminent l'identité d'un assembly : nom, version et culture. Ces attributs constituent le nom complet de l'assembly. Ils sont requis lorsque l'assembly est référencé en code. Vous pouvez définir la version et la culture d'un assembly à l'aide d'attributs. La valeur de nom, cependant, est désignée par le compilateur, par l'IDE Visual Studio dans la Informations de l'assembly, boîte de dialogue ou par Assembly Linker (Al.exe) au moment de la création de l'assembly, d'après le fichier qui contient le manifeste d'assembly. L'attribut AssemblyFlagsAttribute détermine si plusieurs copies de l'assembly peuvent coexister.
Le tableau suivant répertorie les attributs d'identité.
Attribut |
Objectif |
|---|---|
Décrit intégralement l'identité d'un assembly. |
|
Spécifie la version d'un assembly. |
|
Spécifie la culture prise en charge par l'assembly. |
|
Spécifie si un assembly prend en charge l'exécution côte à côte sur le même ordinateur, dans le même processus ou dans le même domaine d'application. |
Attributs d'informations
Vous pouvez utiliser des attributs d'informations pour fournir des informations complémentaires relatives à la société ou au produit au sujet d'un assembly. Le tableau suivant répertorie les attributs d'informations définis dans l'espace de noms System.Reflection.
Attribut |
Objectif |
|---|---|
Définit un attribut personnalisé qui spécifie un nom de produit pour un manifeste d'assembly. |
|
Définit un attribut personnalisé qui spécifie une marque pour un manifeste d'assembly. |
|
Définit un attribut personnalisé qui spécifie une version d'informations pour un manifeste d'assembly. |
|
Définit un attribut personnalisé qui spécifie un nom de société pour un manifeste d'assembly. |
|
Définit un attribut personnalisé qui spécifie un copyright pour un manifeste d'assembly. |
|
Indique au compilateur d'utiliser un numéro de version spécifique pour la ressource de version de fichier Win32. |
|
Indique si l'assembly est conforme à la spécification CLS (Common Language Specification). |
Attributs de manifeste d'assembly
Vous pouvez utiliser les attributs de manifeste d'assembly pour fournir des informations dans le manifeste d'assembly. Cela inclut le titre, la description, l'alias par défaut et la configuration. Le tableau suivant répertorie les attributs de manifeste d'assembly définis dans l'espace de noms System.Reflection.
Attribut |
Objectif |
|---|---|
Définit un attribut personnalisé qui spécifie un titre d'assembly pour un manifeste d'assembly. |
|
Définit un attribut personnalisé qui spécifie une description d'assembly pour un manifeste d'assembly. |
|
Définit un attribut personnalisé qui spécifie une configuration d'assembly (par exemple retail ou debug) pour un manifeste d'assembly. |
|
Définit un alias par défaut convivial pour un manifeste d'assembly. |
Attributs de nom fort
Dans les versions antérieures de Visual Studio, la signature d'assemblys au moyen de noms forts était effectuée avec les attributs de niveau assembly suivants :
Cette méthode est toujours prise en charge, mais il est recommandé de signer les assemblys au moyen de la page Signature du Concepteur de projets. Pour plus d'informations, consultez Page Signature, Concepteur de projets et Comment : signer un assembly (Visual Studio).
Attribut obsolète
L'attribut Obsolete est utilisé pour désigner une entité de programme dont l'utilisation n'est plus recommandée. Chaque utilisation d'une entité désignée comme obsolète génère par la suite un avertissement ou une erreur, selon la façon dont l'attribut est configuré. Par exemple :
<System.Obsolete("use class B")>
Class A
Sub Method()
End Sub
End Class
Class B
<System.Obsolete("use NewMethod", True)>
Sub OldMethod()
End Sub
Sub NewMethod()
End Sub
End Class
[System.Obsolete("use class B")]
class A
{
public void Method() { }
}
class B
{
[System.Obsolete("use NewMethod", true)]
public void OldMethod() { }
public void NewMethod() { }
}
Dans cet exemple, l'attribut Obsolete est appliqué à la classe A et à la méthode B.OldMethod. Comme le deuxième argument du constructeur d'attribut appliqué à B.OldMethod a la valeur true, l'utilisation de cette méthode entraîne une erreur du compilateur, alors que l'utilisation de la classe A n'entraîne qu'un avertissement. Toutefois, B.NewMethod ne produit aucun avertissement ni erreur.
La chaîne fournie comme premier argument au constructeur d'attribut est affichée dans l'avertissement ou l'erreur. Par exemple, utilisé avec les définitions précédentes, le code suivant génère deux avertissements et une erreur :
' Generates 2 warnings:
' Dim a As New A
' Generate no errors or warnings:
Dim b As New B
b.NewMethod()
' Generates an error, terminating compilation:
' b.OldMethod()
// Generates 2 warnings:
// A a = new A();
// Generate no errors or warnings:
B b = new B();
b.NewMethod();
// Generates an error, terminating compilation:
// b.OldMethod();
Deux avertissements pour la classe A sont générés : un pour la déclaration de la référence de classe et un pour le constructeur de classe.
L'attribut Obsolete peut être utilisé sans arguments, mais il est recommandé d'inclure une explication sur la raison pour laquelle l'élément est obsolète et d'indiquer quoi utiliser en remplacement.
Obsolete est un attribut à usage unique et peut être appliqué à toute entité qui autorise des attributs. Obsolete est un alias de ObsoleteAttribute.
Attribut conditionnel
Avec l'attribut Conditional, l'exécution d'une méthode dépend d'un identificateur de prétraitement. L'attribut Conditional est un alias de ConditionalAttribute et peut s'appliquer à une méthode ou une classe d'attributs.
Dans cet exemple, Conditional est appliqué à une méthode pour activer ou désactiver l'affichage d'informations de diagnostic spécifiques au programme :
#Const TRACE_ON = True
Imports System
Imports System.Diagnostics
Module TestConditionalAttribute
Public Class Trace
<Conditional("TRACE_ON")>
Public Shared Sub Msg(ByVal msg As String)
Console.WriteLine(msg)
End Sub
End Class
Sub Main()
Trace.Msg("Now in Main...")
Console.WriteLine("Done.")
End Sub
End Module
#define TRACE_ON
using System;
using System.Diagnostics;
public class Trace
{
[Conditional("TRACE_ON")]
public static void Msg(string msg)
{
Console.WriteLine(msg);
}
}
public class ProgramClass
{
static void Main()
{
Trace.Msg("Now in Main...");
Console.WriteLine("Done.");
}
}
Si l'identificateur TRACE_ON n'est pas défini, aucune sortie de trace n'est affichée.
L'attribut Conditional est souvent utilisé avec l'identificateur DEBUG pour activer la trace et enregistrer des fonctionnalités pour des versions de débogage mais non pour des versions Release, de la manière suivante :
<Conditional("DEBUG")>
Shared Sub DebugMethod()
End Sub
[Conditional("DEBUG")]
static void DebugMethod()
{
}
Lorsqu'une méthode marquée comme conditionnelle est appelée, la présence ou l'absence du symbole de prétraitement spécifié détermine si l'appel est inclus ou omis. Si le symbole est défini, l'appel est inclus ; sinon, il est omis. Conditional offre une solution à la fois plus efficace, plus élégante et moins sujette aux erreurs que les méthodes englobantes contenues dans les blocs #if…#endif, telles que la suivante :
#If DEBUG Then
Sub ConditionalMethod()
End Sub
#End If
#if DEBUG
void ConditionalMethod()
{
}
#endif
Une méthode conditionnelle doit figurer dans une déclaration de classe ou de struct, et ne doit pas avoir de valeur de retour.
Utilisation de plusieurs identificateurs
Si une méthode comporte plusieurs attributs Conditional, un appel à cette dernière est inclus si l'un des symboles conditionnels au moins est défini (en d'autres termes, les symboles sont liés logiquement par l'opérateur OR). Dans cet exemple, la présence de A ou B résulte en un appel de méthode :
<Conditional("A"), Conditional("B")>
Shared Sub DoIfAorB()
End Sub
[Conditional("A"), Conditional("B")]
static void DoIfAorB()
{
// ...
}
Pour lier logiquement les symboles au moyen de l'opérateur AND, vous pouvez définir des méthodes conditionnelles en série. Par exemple, la deuxième méthode ci-dessous ne s'exécute que si A et B sont définis :
<Conditional("A")>
Shared Sub DoIfA()
DoIfAandB()
End Sub
<Conditional("B")>
Shared Sub DoIfAandB()
' Code to execute when both A and B are defined...
End Sub
[Conditional("A")]
static void DoIfA()
{
DoIfAandB();
}
[Conditional("B")]
static void DoIfAandB()
{
// Code to execute when both A and B are defined...
}
Utilisation du conditionnel avec des classes d'attributs
L'attribut Conditional peut également être appliqué à une définition de classe d'attributs. Dans cet exemple, l'attribut Documentation personnalisé n'ajoute des informations aux métadonnées que si DEBUG est défini.
<Conditional("DEBUG")>
Public Class Documentation
Inherits System.Attribute
Private text As String
Sub New(ByVal doc_text As String)
text = doc_text
End Sub
End Class
Class SampleClass
' This attribute will only be included if DEBUG is defined.
<Documentation("This method displays an integer.")>
Shared Sub DoWork(ByVal i As Integer)
System.Console.WriteLine(i)
End Sub
End Class
[Conditional("DEBUG")]
public class Documentation : System.Attribute
{
string text;
public Documentation(string text)
{
this.text = text;
}
}
class SampleClass
{
// This attribute will only be included if DEBUG is defined.
[Documentation("This method displays an integer.")]
static void DoWork(int i)
{
System.Console.WriteLine(i.ToString());
}
}
Attributs des informations de l'appelant
À l'aide des attributs d'informations de l'appelant, vous pouvez obtenir des informations sur l'appellant d'une méthode. Vous pouvez obtenir le chemin d'accès du fichier de code source, le numéro de ligne dans le code source, puis du nom du membre de l'appelant.
Pour obtenir des informations de membre sur l'appelant, vous utilisez les attributs qui sont appliqués aux paramètres optionnels. Chaque paramètre optionnel spécifie une valeur par défaut. Le tableau suivant répertorie les attributs d'informations de l'appelant définis dans l'espace de noms System.Runtime.CompilerServices :
Attribut |
Description |
Type |
Chemin d'accès complet du fichier source qui contient l'appelant. C'est le chemin d'accès au moment de la compilation. |
String |
|
Numéro de ligne dans le fichier source à partir duquel la méthode est appelée. |
Integer |
|
Nom de la méthode ou nom de la propriété de l'appelant. Pour plus d’informations, consultez Informations relatives à l'appelant (C# et Visual Basic). |
String |
Pour plus d'informations sur les attributs des informations de l'appelant, consultez Informations relatives à l'appelant (C# et Visual Basic).
Attributs Visual Basic
Le tableau suivant répertorie les attributs spécifiques à Visual Basic.
Attribut |
Objectif |
|---|---|
Indique au compilateur que la classe doit être exposée comme un objet COM. |
|
Permet aux membres de module d'être accessibles à l'aide uniquement de la qualification nécessaire pour le module. |
|
Spécifie la taille d'une chaîne de longueur fixe dans une structure à utiliser avec les fonctions d'entrée et de sortie de fichier. |
|
Spécifie la taille d'un tableau fixe dans une structure à utiliser avec les fonctions d'entrée et de sortie de fichier. |
COMClassAttribute
Utilisez l'attribut COMClassAttribute pour simplifier le processus de création des composants COM à partir de Visual Basic. Les objets COM sont très différents des assemblys .NET Framework, et sans l'attribut COMClassAttribute, vous devez mettre en œuvre un certain nombre d'opérations pour générer un objet COM à partir de Visual Basic. Un grand nombre de ces opérations sont effectuées automatiquement par le compilateur pour les classes marquées avec l'attribut COMClassAttribute.
HideModuleNameAttribute
Utilisez l'attribut HideModuleNameAttribute pour que les membres de module soient accessibles uniquement au moyen de la qualification requise pour le module.
VBFixedStringAttribute
Utilisez l'attribut VBFixedStringAttribute pour forcer Visual Basic à créer une chaîne de longueur fixe. Les chaînes ont une taille variable par défaut, et cet attribut est utile pour stocker des chaînes dans des fichiers. Le code suivant illustre cette méthode :
Structure Worker
' The runtime uses VBFixedString to determine
' if the field should be written out as a fixed size.
<VBFixedString(10)> Public LastName As String
<VBFixedString(7)> Public Title As String
<VBFixedString(2)> Public Rank As String
End Structure
VBFixedArrayAttribute
L'attribut VBFixedArrayAttribute permet de déclarer des tableaux de taille fixe. Comme les chaînes Visual Basic , les tableaux ont par défaut une longueur variable. Cet attribut est utile lors de la sérialisation ou de l'écriture de données dans des fichiers.
Voir aussi
Référence
Réflexion (C# et Visual Basic)
Accès à des attributs à l'aide de la réflexion (C# et Visual Basic)