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é.

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.

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.

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 :

• AssemblyKeyFileAttribute

• AssemblyKeyNameAttribute

• AssemblyDelaySignAttribute

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 :

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.

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)

System.Reflection

Attribute

Concepts

Guide de programmation C#

Autres ressources

Guide de programmation Visual Basic

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