<add>-Element für <listeners> für <source>

Artikel
08/20/2008

Aktualisiert: November 2007

Fügt der Listeners-Auflistung für eine Ablaufverfolgungsquelle einen Listener hinzu.

<configuration>-Element
  <system.diagnostics>-Element
    <sources>-Element
      <source>-Element
        <listeners>-Element für <trace>
          <add>-Element für <listeners> für <source>

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

Attribute und Elemente

In den folgenden Abschnitten werden Attribute und untergeordnete sowie übergeordnete Elemente beschrieben.

Attribute

Attribut	Beschreibung
type	Erforderliches Attribut. Gibt den Typ des Listeners an. Sie müssen eine Zeichenfolge verwenden, die die in Angeben vollständig gekennzeichneter Typnamen angegebenen Anforderungen erfüllt.
initializeData	Optionales Attribut. Die für die angegebene Klasse an den Konstruktor übergebene Zeichenfolge. Wenn die Klasse über keinen Konstruktor verfügt, der eine Zeichenfolge akzeptiert, wird eine ConfigurationException ausgelöst.
name	Optionales Attribut. Gibt den Namen des Listeners an.
traceOutputOptions	Optionales Attribut. Gibt den TraceOutputOptions-Eigenschaftenwert für den Ablaufverfolgungslistener an.
[benutzerdefinierte Attribute]	Optionale Attribute. Gibt den Wert der für den Listener spezifischen Attribute an, die von der GetSupportedAttributes-Methode für diesen Listener ermittelt werden. Delimiter ist ein Beispiel für ein zusätzliches Attribut, das für die DelimitedListTraceListener-Klasse eindeutig ist.

Untergeordnete Elemente

Element	Beschreibung
<filter>-Element für <add> für <listeners> für <source>	Fügt einem Listener in der Listeners-Auflistung für eine Ablaufverfolgungsquelle einen Filter hinzu.

Übergeordnete Elemente

Element	Beschreibung
configuration	Das Stammelement in jeder Konfigurationsdatei, das von der Common Language Runtime und den .NET Framework-Anwendungen verwendet wird.
system.diagnostics	Gibt die Ablaufverfolgungslistener, die Meldungen sammeln, speichern und weiterleiten, sowie die Ebene an, auf der ein Ablaufverfolgungsschalter festgelegt wird.
sources	Enthält Ablaufverfolgungsquellen, die Ablaufverfolgungsmeldungen initiieren.
source	Gibt eine Ablaufverfolgungsquelle an, die Ablaufverfolgungsmeldungen initiiert.
listeners	Gibt Listener an, die Meldungen sammeln, speichern und weiterleiten.

Hinweise

Die im Lieferumfang des .NET Framework enthaltenen Listenerklassen sind von der TraceListener-Klasse abgeleitet.

Wenn Sie kein name-Attribut des Ablaufverfolgungslisteners angeben, entspricht die Name-Eigenschaft des Ablaufverfolgungslisteners standardmäßig einer leeren Zeichenfolge (""). Wenn die Anwendung über nur einen Listener verfügt, können Sie ihn ohne Angabe eines Namens hinzufügen und unter Angabe einer leeren Zeichenfolge für den Namen entfernen. Wenn die Anwendung hingegen mehrere Listener aufweist, müssen Sie für jeden Ablaufverfolgungslistener einen eindeutigen Namen angeben, sodass die einzelnen Ablaufverfolgungslistener in der TraceSource.Listeners-Auflistung ermittelt und verwaltet werden können.

Tipp

Wenn Sie mehrere Ablaufverfolgungslistener des gleichen Typs und mit dem gleichen Namen hinzufügen, wird der Listeners-Auflistung nur ein einziger Ablaufverfolgungslistener dieses Typs und Namens hinzugefügt. Sie können der Listeners-Auflistung jedoch programmgesteuert mehrere identische Listener hinzufügen.

Der Wert des initializeData-Attributs hängt von der Art des erstellten Listeners ab. initializeData muss nicht für alle Ablaufverfolgungslistener angegeben werden.

Tipp

Wenn Sie das initializeData-Attribut verwenden, wird möglicherweise die Compilerwarnung "Das Attribut "initializeData" ist nicht deklariert" angezeigt. Diese Warnung wird angezeigt, da die Konfigurationseinstellungen anhand der abstrakten Basisklasse TraceListener überprüft werden, die das initializeData-Attribut nicht erkennt. In der Regel können Sie diese Warnung für Implementierungen von Ablaufverfolgungslistenern ignorieren, die über einen Konstruktor mit einem Parameter verfügen.

In der folgenden Tabelle werden die im Lieferumfang des .NET Framework enthaltenen Ablaufverfolgungslistener aufgeführt und die Werte der zugehörigen initializeData-Attribute erläutert.

Ablaufverfolgungslistener-Klasse	initializeData-Attributwert
System.Diagnostics.ConsoleTraceListener	Der useErrorStream-Wert für den ConsoleTraceListener-Konstruktor. Legen Sie das initializeData-Attribut auf "true" fest, um die Ablaufverfolgungs- und Debugausgabe in den Standardfehlerstream zu schreiben, oder legen Sie es auf "false" fest, um in den Standardausgabestream zu schreiben.
System.Diagnostics.DelimitedListTraceListener	Der Name der Datei, in die der DelimitedListTraceListener schreibt.
System.Diagnostics.EventLogTraceListener	Der Name einer vorhandenen Ereignisprotokollquelle.
System.Diagnostics.EventSchemaTraceListener	Der Name der Datei, in die von EventSchemaTraceListener geschrieben wird.
System.Diagnostics.TextWriterTraceListener	Der Name der Datei, in die der TextWriterTraceListener schreibt.
System.Diagnostics.XmlWriterTraceListener	Der Name der Datei, in die der XmlWriterTraceListener schreibt.

Konfigurationsdatei

Dieses Element kann in der Computerkonfigurationsdatei (Machine.config) und in der Anwendungskonfigurationsdatei verwendet werden.

Beispiel

Im folgenden Codebeispiel wird veranschaulicht, wie der Listeners-Auflistung für die Ablaufverfolgungsquelle TraceSourceApp mithilfe der <add>-Elemente die Listener console und textListener hinzugefügt werden. Der textListener-Listener schreibt die Ablaufverfolgungsausgabe in die Datei 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>