<add>, élément de <sharedListeners>

Article
08/21/2008

Mise à jour : novembre 2007

Ajoute un écouteur à la collection sharedListeners. sharedListeners est une collection d'écouteurs qui peut être référencée par tout <source>, élément ou <trace>, élément. Par défaut, les écouteurs de la collection sharedListeners ne sont pas placés dans une collection Listeners. Leur nom doit être ajouté à <source>, élément ou à <trace>, élément. Il n'est pas possible d'obtenir les écouteurs de la collection sharedListeners dans le code au moment de l'exécution.

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

<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
name	Attribut requis. Spécifie le nom de l'écouteur utilisé pour ajouter l'écouteur partagé à une collection Listeners.
type	Attribut requis. Spécifie le type de l'écouteur. Vous devez utiliser une chaîne qui répond aux conditions énoncé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 requis.

Spécifie le nom de l'écouteur utilisé pour ajouter l'écouteur partagé à une collection Listeners.

type

Attribut requis.

Spécifie le type de l'écouteur. Vous devez utiliser une chaîne qui répond aux conditions énoncé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.

Éléments enfants

Élément	Description
<filter>, élément de <add> pour <sharedListeners>	Ajoute un filtre à un écouteur de la collection sharedListeners.

É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 traçage qui collectent, stockent et routent des messages, ainsi que le niveau auquel un commutateur de traçage est défini.
sharedListeners	Collection d'écouteurs qui peut être référencée par tout élément source ou de trace.

Notes

Les classes d'écouteur livrées avec le .NET Framework dérivent de la classe TraceListener. La valeur de l'attribut name est utilisée pour ajouter l'écouteur partagé à une collection Listeners pour une trace ou une source de trace. 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'écouteur de traces	initializeData, valeur d'attribut
ConsoleTraceListener	Valeur useErrorStream pour le constructeur ConsoleTraceListener. Affectez la valeur true à l'attribut initializeData pour écrire la sortie de la trace et du débogage dans le flux d'erreurs standard ; affectez-lui la valeur false pour l'écrire dans le flux de sortie standard.
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.
XmlWriterTraceListener	Nom du fichier dans lequel XmlWriterTraceListener écrit.

Fichier de configuration

Cet élément peut être utilisé dans le fichier de configuration machine (Machine.config) et dans le fichier de configuration de l'application.

Exemple

L'exemple suivant montre comment utiliser des éléments <add> pour ajouter le TextWriterTraceListenertextListener à la collection sharedListeners. Le nom du textListener est ajouté à la collection Listeners pour la source de trace TraceSourceApp. L'écouteur textListener écrit la sortie de la 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>