Élément <add> pour <listeners> pour <source>

  • Article

Ajoute un écouteur à la collection Listeners pour une source de trace.

<configuration>
  <system.diagnostics>
    <sources>
      <source>
        <listeners>
          <add>

Syntaxe

<add name="name"
  type="TraceListenerClassName, Version, Culture, PublicKeyToken"  
  initializeData="data"/>

Attributs et éléments

Les sections suivantes décrivent des attributs, des éléments enfants et des éléments parents.

Attributs

Attribut Description
type Attribut obligatoire, sauf si vous référencez un écouteur dans la collection sharedListeners, auquel cas vous devez uniquement y faire référence par le nom (voir l’exemple).

Spécifie le type de l’écouteur. Vous pouvez utiliser une chaîne qui répond aux exigences spécifiées dans Spécification des noms de types complets.
initializeData Attribut facultatif.

Chaîne transmise au constructeur pour la classe spécifiée. Un exception ConfigurationException est levée si la classe ne dispose pas de constructeur qui accepte une chaîne.
name Attribut facultatif.

Spécifie le nom de l’écouteur.
traceOutputOptions Attribut facultatif.

Spécifie la valeur de la propriété TraceOutputOptions pour l’écouteur de trace.
[attributs personnalisés] Attributs facultatifs.

Spécifie la valeur des attributs propres à l’écouteur identifiés par la méthode GetSupportedAttributesde cet écouteur. Delimiter est un exemple d’attribut supplémentaire unique à la classe DelimitedListTraceListener.

Éléments enfants

Élément Description
<filter> Ajoute un filtre à un écouteur dans la collection Listeners pour une source de trace.

Éléments parents

Élément Description
configuration Élément racine de chaque fichier de configuration utilisé par le Common Language Runtime et les applications .NET Framework.
system.diagnostics Spécifie les écouteurs de trace qui collectent, stockent et acheminent les messages, ainsi que le niveau auquel un commutateur de trace est défini.
sources Contient les sources de trace qui lancent des messages de traçage.
source Spécifie une source de trace qui lance des messages de traçage.
listeners Spécifie les écouteurs qui collectent, stockent et routent les messages.

Notes

Les classes d’écouteur fournies avec .NET Framework dérivent de la classe TraceListener.

Si vous ne spécifiez pas l’attribut name de l’écouteur de trace, la propriété Name de l’écouteur de trace est définie par défaut sur une chaîne vide (""). Si votre application ne dispose que d’un seul écouteur, vous pouvez l’ajouter sans spécifier de nom et le supprimer en spécifiant une chaîne vide pour le nom. Cependant, si votre application possède plusieurs écouteurs, vous devez spécifier un nom unique pour chaque écouteur de trace, ce qui vous permet d’identifier et de gérer individuellement chaque écouteur de trace de la collection TraceSource.Listeners.

Notes

L’ajout de plusieurs écouteurs de trace de même type et de même nom entraîne l’ajout d’un seul écouteur de trace de ce type et de ce nom à la collection Listeners. Cependant, vous pouvez ajouter par programmation plusieurs écouteurs identiques à la collection Listeners.

La valeur de l’attribut initializeData dépend du type d’écouteur que vous créez. Pour certains écouteurs de trace, il n’est pas nécessaire de spécifier initializeData.

Notes

Quand vous utilisez l’attribut initializeData, il se peut que obteniez un avertissement du compilateur indiquant que l’attribut « InitializeData » n’est pas déclaré. Cet avertissement apparaît, car les paramètres de configuration sont validés par rapport à la classe de base abstraite TraceListener, qui ne reconnaît pas l’attribut initializeData. En règle générale, vous pouvez ignorer cet avertissement pour les implémentations d’écouteur de trace doté d’un constructeur qui accepte un paramètre.

Le tableau suivant présente les écouteurs de trace qui accompagnent .NET Framework et décrit la valeur de leurs attributs initializeData.

Classe d’écouteur de trace Valeur d’attribut initializeData
System.Diagnostics.ConsoleTraceListener Valeur useErrorStream du constructeur ConsoleTraceListener. Définissez l’attribut initializeData sur « true » pour écrire la sortie de trace et de débogage dans le flux d’erreur standard ; définissez-le sur « false » pour écrire dans le flux de sortie standard.
System.Diagnostics.DelimitedListTraceListener Nom du fichier vers lequel DelimitedListTraceListener écrit.
System.Diagnostics.EventLogTraceListener Nom d'une source existante de journal des événements.
System.Diagnostics.EventSchemaTraceListener Nom du fichier dans lequel EventSchemaTraceListener écrit.
System.Diagnostics.TextWriterTraceListener Nom du fichier dans lequel TextWriterTraceListener écrit.
System.Diagnostics.XmlWriterTraceListener Nom du fichier dans lequel XmlWriterTraceListener écrit.

Fichier de configuration

Cet élément peut être défini dans le fichier de configuration de l’application ou dans le fichier de configuration de l’ordinateur (Machine.config).

Exemple

L’exemple suivant montre comment utiliser des éléments <add> pour ajouter les écouteurs console et textListener à la collection Listeners pour la source de trace TraceSourceApp. L’écouteur textListener écrit la sortie de trace dans le fichier myListener.log.

<configuration>  
  <system.diagnostics>  
    <sources>  
      <source name="TraceSourceApp" switchName="sourceSwitch"
        switchType="System.Diagnostics.SourceSwitch">  
        <listeners>  
          <add name="console"
            type="System.Diagnostics.ConsoleTraceListener"/>  
          <add name="textListener"/>  
          <remove name="Default"/>  
        </listeners>  
      </source>  
    </sources>  
    <sharedListeners>  
      <add name="textListener"
        type="System.Diagnostics.TextWriterTraceListener"
        initializeData="myListener.log"/>  
    </sharedListeners>  
    <switches>  
      <add name="sourceSwitch" value="Warning"/>  
    </switches>  
  </system.diagnostics>  
</configuration>

Voir aussi