Comment : configurer les commutateurs de trace

Mise à jour : novembre 2007

Une fois votre application distribuée, vous pouvez toujours activer ou désactiver la sortie de trace en configurant des commutateurs de traçage dans votre application. Pour configurer un commutateur, il faut changer sa valeur à partir d'une source externe une fois qu'il a été initialisé. Vous pouvez modifier les valeurs des objets commutateur à l'aide du fichier de configuration. Vous configurez un commutateur de traçage pour pouvoir l'activer et le désactiver ou pour définir son niveau en déterminant la quantité et le type de messages passés aux écouteurs.

Vos commutateurs sont configurés à l'aide du fichier .config. Pour une application Web, il s'agit du fichier Web.config associé au projet. Dans une application Windows, ce fichier est intitulé (nom de l'application).exe.config. Dans une application déployée, ce fichier doit résider dans le même dossier que le fichier exécutable.

Lorsque votre application exécute le code qui crée pour la première fois une instance d'un commutateur, elle recherche dans le fichier de configuration des informations sur le niveau de traçage pour le commutateur nommé. Le système de traçage examine le fichier de configuration une seule fois pour un commutateur particulier (la première fois que votre application crée le commutateur).

Dans une application déployée, vous activez le code de traçage en reconfigurant les objets commutateur lorsque votre application ne s'exécute pas. Généralement, cela implique l'activation et la désactivation des objets commutateur ou le changement des niveaux de traçage, puis le redémarrage de votre application.

Lorsque vous créez une instance d'un commutateur, vous l'initialisez également en spécifiant deux arguments : displayName et description. L'argument displayName du constructeur définit la propriété Switch.DisplayName de l'instance de classe Switch. L'argument displayName correspond au nom utilisé pour configurer le commutateur dans le fichier .config. Quant à l'argument description, il devrait retourner une brève description du commutateur, ainsi que les messages qu'il contrôle.

En plus de spécifier le nom d'un commutateur à configurer, vous devez aussi spécifier une valeur pour le commutateur. La valeur est un entier. Pour BooleanSwitch, la valeur zéro correspond à Off et toute autre valeur différente de zéro correspond à On. Pour un TraceSwitch, 0, 1, 2, 3 et 4 correspondent respectivement à Off, Error, Warning, Info et Verbose. Toute valeur supérieure à 4 est traitée comme Verbose et toute valeur inférieure à 0 est traitée comme Off.

Remarque :
Dans le .NET Framework version 2.0, vous pouvez utiliser le texte pour spécifier la valeur d'un commutateur. Par exemple, true pour un BooleanSwitch ou le texte représentant une valeur d'énumération telle que Error pour un TraceSwitch. La ligne <add name="myTraceSwitch" value="Error" /> équivaut à <add name="myTraceSwitch" value="1" />.

Pour que les utilisateurs finals puissent configurer les commutateurs de traçage d'une application, vous devez fournir des informations détaillées sur les commutateurs dans votre application. Vous devriez détailler ce que les commutateurs contrôlent et la manière dont ils sont activés et désactivés. Vous devriez également fournir aux utilisateurs finals un fichier .config contenant l'aide nécessaire dans les commentaires.

Pour créer et configurer des commutateurs de traçage

1. Créez vos commutateurs dans le code. Pour plus d'informations, consultez Création et initialisation des commutateurs de traçage.

2. Si votre projet ne contient pas de fichier de configuration (app.config ou Web.config), dans le menu Projet, choisissez Ajouter un nouvel élément.

   • Visual Basic : Dans la boîte de dialogue Ajouter un nouvel élément, choisissez Fichier de configuration de l'application.

     Le fichier de configuration de l'application est créé et ouvert. Il s'agit d'un document XML dont l'élément racine est <configuration>..

   • Visual C# : Dans la boîte de dialogue Ajouter un nouvel élément, choisissez Fichier XML. Nommez ce fichier app.config. Dans l'Éditeur XML, après la déclaration XML, ajoutez les balises suivantes :

     <configuration>
     </configuration>
     

     Lorsque votre projet est compilé, le fichier app.config est copié dans le dossier de sortie du projet et renommé applicationname.exe.config.

3. Après la balise <configuration> , mais avant la balise </configuration> , ajoutez le code XML approprié pour configurer vos commutateurs. Les exemples suivants montrent un commutateur BooleanSwitch avec une propriété DisplayName ayant la valeur DataMessageSwitch et un commutateur TraceSwitch avec une propriété DisplayName ayant la valeur TraceLevelSwitch.

   <system.diagnostics>
      <switches>
         <add name="DataMessagesSwitch" value="0" />
         <add name="TraceLevelSwitch" value="0" />
      </switches>
   </system.diagnostics>
   

   Dans cette configuration, les deux commutateurs sont désactivés.

4. Si vous avez besoin d'activer un commutateur BooleanSwitch, tel que DataMessagesSwitch montré dans l'exemple précédent, remplacez Value par un entier différent de 0.

5. Si vous avez besoin d'activer un commutateur TraceSwitch, tel que TraceLevelSwitch montré dans l'exemple précédent, remplacez Value par le paramètre correspondant au niveau approprié (de 1 à 4).

6. Ajoutez des commentaires dans le fichier .config de sorte que l'utilisateur puisse facilement comprendre les valeurs à modifier pour configurer les commutateurs de manière appropriée.

   L'exemple suivant montre à quoi le code final, commentaires inclus, peut ressembler :

   <system.diagnostics>
      <switches>
         <!-- This switch controls data messages. In order to receive data 
            trace messages, change value="0" to value="1" -->
         <add name="DataMessagesSwitch" value="0" />
         <!-- This switch controls general messages. In order to 
            receive general trace messages change the value to the 
            appropriate level. "1" gives error messages, "2" gives errors 
            and warnings, "3" gives more detailed error information, and 
            "4" gives verbose trace information -->
         <add name="TraceLevelSwitch" value="0" />
      </switches>
   </system.diagnostics>
   

Voir aussi

Tâches

Comment : ajouter des instructions de traçage dans le code d'une application

Concepts

Introduction à l'instrumentation et au traçage

Commutateurs de traçage

Référence

Schéma des paramètres de traçage et de débogage

Autres ressources

Traçage et instrumentation d'applications