<add>, élément de <listeners> pour <trace>

Article
08/21/2008

Mise à jour : novembre 2007

Ajoute un écouteur à la collection Listeners.

<configuration>, élément
  <system.diagnostics>, élément
    <trace>, élément
      <listeners>, élément de <trace>
        <add>, élément de <listeners> pour <trace>

<add name="name" 
     type="trace listener class name, 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 requis. Spécifie le type de l'écouteur. Vous devez utiliser une chaîne conforme aux exigences spécifiées dans Spécification des noms de types qualifiés complets.
initializeData	Attribut facultatif. Chaîne passée au constructeur pour la classe spécifiée.
name	Attribut facultatif. Spécifie le nom de l'écouteur.

type

Attribut requis.

Spécifie le type de l'écouteur. Vous devez utiliser une chaîne conforme aux exigences spécifiées dans Spécification des noms de types qualifiés complets.

initializeData

Attribut facultatif.

Chaîne passée au constructeur pour la classe spécifiée.

name

Attribut facultatif.

Spécifie le nom de l'écouteur.

Éléments enfants

Aucun.

É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.
listeners	Spécifie un écouteur qui collecte, stocke et route des messages. Les écouteurs dirigent la sortie de traçage vers une cible appropriée.
system.diagnostics	Spécifie l'élément racine de la section de configuration ASP.NET.
trace	Contient des écouteurs qui collectent, stockent et routent des messages de traçage.

Notes

Les classes Debug et Trace partagent la même collection Listeners. Si vous ajoutez un objet Listener à la collection dans l'une de ces classes, l'autre classe utilise le même écouteur. Les classes d'écouteur dérivent de la classe TraceListener.

Si vous ne spécifiez pas l'attribut name de l'écouteur de la trace, le Name de l'écouteur de la trace prend comme valeur par défaut une chaîne vide (""). Si votre application n'a qu'un écouteur, vous pouvez l'ajouter sans spécifier de nom et le supprimer en spécifiant une chaîne vide en tant que nom. Toutefois, si votre application a plusieurs écouteurs, vous devez spécifier des noms uniques pour chaque écouteur de la trace, ce qui permet d'identifier et de gérer des écouteurs de trace individuels dans les collections Listeners et Listeners.

Remarque :
Si vous ajoutez plusieurs écouteurs de la trace possédant le même type et le même nom, un seul écouteur de la trace de ce type et de ce nom est ajouté à la collection Listeners. Toutefois, vous pouvez ajouter par programme plusieurs écouteurs identiques à la collection Listeners.

La valeur de l'attribut initializeData dépend du type d'écouteur que vous créez. Il n'est pas nécessaire de spécifier initializeData pour tous les écouteurs de la trace.

Remarque :
Lorsque vous utilisez l'attribut initializeData, le message d'avertissement du compilateur suivant peut s'afficher : « L'attribut 'initializeData' n'est pas déclaré. ». Cet avertissement s'affiche, 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 général, vous pouvez ignorer cet avertissement pour les implémentations de l'écouteur de la trace disposant d'un constructeur qui accepte un paramètre.

Lorsque vous utilisez l'attribut initializeData, le message d'avertissement du compilateur suivant peut s'afficher : « L'attribut 'initializeData' n'est pas déclaré. ». Cet avertissement s'affiche, 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 général, vous pouvez ignorer cet avertissement pour les implémentations de l'écouteur de la trace disposant d'un constructeur qui accepte un paramètre.

Le tableau suivant présente les écouteurs de la trace inclus avec le .NET Framework et décrit la valeur de leur attribut initializeData.

Classe d'écouteurs de traces	initializeData, valeur d'attribut
System.Diagnostics.ConsoleTraceListener	Valeur useErrorStream pour le constructeur ConsoleTraceListener. Affectez la valeur "true" à l'attribut initializeData pour écrire la sortie de la trace et de débogage à Console.Error ; "false" pour écrire à Console.Out.
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.

Exemple

L'exemple suivant montre comment utiliser les éléments <add> pour ajouter les écouteurs MyListener et MyEventListener à la collection Listeners. MyListener crée un fichier intitulé MyListener.log et écrit la sortie dans celui-ci. MyEventListener crée une entrée dans le journal des événements.

<configuration>
   <system.diagnostics>
      <trace autoflush="true" indentsize="0">
         <listeners>
            <add name="myListener" type="System.Diagnostics.TextWriterTraceListener, system, version=1.0.3300.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" initializeData="c:\myListener.log" />
            <add name="MyEventListener"
                 type="System.Diagnostics.EventLogTraceListener, system, version=1.0.3300.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"                 initializeData="MyConfigEventLog"/>
            <add name="configConsoleListener"
                 type="System.Diagnostics.ConsoleTraceListener, system, version=1.0.3300.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"/>
         </listeners>
      </trace>
   </system.diagnostics>
</configuration>