Guide pratique pour créer, initialiser et configurer des commutateurs de trace

Les commutateurs de trace vous permettent d’activer, désactiver et filtrer la sortie de suivi.

Création et initialisation d’un commutateur de trace

Pour utiliser des commutateurs de trace, vous devez d’abord les créer et les placer dans votre code. Il existe deux classes prédéfinies à partir desquelles vous pouvez créer des objets switch : la System.Diagnostics.BooleanSwitch classe et la System.Diagnostics.TraceSwitch classe. Vous devez utiliser BooleanSwitch si vous vous souciez uniquement de savoir si un message de suivi s’affiche ou non ; si TraceSwitch vous souhaitez faire une distinction entre les niveaux de suivi. Si vous utilisez un TraceSwitch, vous pouvez définir vos propres messages de débogage et les associer à différents niveaux de trace. Vous pouvez utiliser les deux types de commutateurs avec le traçage ou le débogage. Par défaut, un BooleanSwitch est désactivé et un TraceSwitch est défini sur le niveau TraceLevel.Off. Les commutateurs de trace peuvent être créés et placés dans n’importe quelle partie de votre code qui peut les utiliser.

Bien que vous puissiez définir des niveaux de trace et d’autres options de configuration dans le code, nous vous recommandons d’utiliser le fichier de configuration pour gérer l’état de vos commutateurs. Cela est dû au fait que la gestion de la configuration de vos commutateurs dans le système de configuration vous offre une plus grande flexibilité : vous pouvez activer et désactiver différents commutateurs et niveaux de modification sans recompiler votre application.

Pour créer et initialiser un commutateur de trace

1. Définissez un commutateur comme type System.Diagnostics.BooleanSwitch ou type System.Diagnostics.TraceSwitch et définissez le nom et la description du commutateur.

2. Configurez votre commutateur de trace. Pour plus d’informations, consultez Configuration des commutateurs de trace.

   Le code suivant crée deux commutateurs, l’un de chaque type :

   Dim dataSwitch As New BooleanSwitch("Data", "DataAccess module")
   Dim generalSwitch As New TraceSwitch("General", "Entire application")
   

   System.Diagnostics.BooleanSwitch dataSwitch =
      new System.Diagnostics.BooleanSwitch("Data", "DataAccess module");
   System.Diagnostics.TraceSwitch generalSwitch =
      new System.Diagnostics.TraceSwitch("General",
      "Entire application");
   

Configuration des commutateurs de trace

Une fois que votre application a été distribuée, vous pouvez toujours activer ou désactiver la sortie de trace en configurant les commutateurs de trace dans votre application. La configuration d’un commutateur signifie modifier sa valeur d’une source externe après son initialisation. Vous pouvez modifier les valeurs des objets switch à l’aide du fichier de configuration. Vous configurez un commutateur de trace pour l’activer et le désactiver, ou pour définir son niveau, en déterminant la quantité et le type de messages qu’il transmet 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 nommé (nom de l’application).exe.config. Dans une application déployée, ce fichier doit résider dans le même dossier que l’exécutable.

Lorsque votre application exécute le code qui crée une instance d’un commutateur pour la première fois, elle vérifie le fichier de configuration pour obtenir des informations de niveau trace sur le commutateur nommé. Le système de suivi 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 trace en reconfigurant les objets switch lorsque votre application n’est pas en cours d’exécution. En règle générale, cela implique d’activer et de désactiver les objets switch ou en modifiant les niveaux de suivi, puis en redémarrant votre application.

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

En plus de spécifier le nom d’un commutateur à configurer, vous devez également spécifier une valeur pour le commutateur. Cette valeur est un entier. Pour BooleanSwitch, une valeur de 0 correspond à Off, et toute valeur différente de zéro correspond à On. Pour TraceSwitch, 0,1,2,3 et 4 correspondent off, Error, Warning, Info et Verbose, respectivement. Tout nombre supérieur à 4 est traité comme détaillé et n’importe quel nombre inférieur à zéro est traité comme Désactivé.

Pour que les utilisateurs finaux puissent configurer les commutateurs de trace d’une application, vous devez fournir une documentation détaillée sur les commutateurs de votre application. Vous devez détailler les commutateurs qui contrôlent ce qui et comment les activer et les désactiver. Vous devez également fournir à votre utilisateur final un fichier .config qui dispose de l’aide appropriée dans les commentaires.

Pour configurer les commutateurs de trace

1. Pour utiliser des commutateurs de trace, vous devez d’abord les créer et les placer dans votre code, comme décrit dans la section Création et initialisation d’un commutateur de trace.

2. Si votre projet ne contient pas de fichier de configuration (app.config ou Web.config), puis dans le menu Projet , sélectionnez 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 le code XML suivant :

     <configuration>
     </configuration>
     

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

3. Après la <configuration> balise, mais avant la </configuration> balise, ajoutez le code XML approprié pour configurer vos commutateurs. Les exemples suivants illustrent un BooleanSwitch avec une propriété DisplayName de DataMessageSwitch, et un TraceSwitch avec une propriété DisplayName de 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 devez activer un booléenSwitch, tel que DataMessagesSwitch illustré dans l’exemple précédent, remplacez la valeur par un entier autre que 0.

5. Si vous devez activer un commutateur TraceSwitch, tel que TraceLevelSwitch illustré dans l’exemple précédent, remplacez la valeur par le paramètre de niveau approprié (1 à 4).

6. Ajoutez des commentaires au fichier .config afin que l’utilisateur final ait une compréhension claire des valeurs à modifier pour configurer les commutateurs de manière appropriée.

   L’exemple suivant montre comment le code final, y compris les commentaires, peut se présenter :

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

• Suivi et instrumentation d’applications
• Guide pratique pour ajouter des instructions de trace au code d’application
• Commutateurs de trace
• Schéma des paramètres de trace et de débogage