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

Artikel
05/10/2023

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

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

Syntax

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

Attribute und Elemente

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

Attribute

Attribut	BESCHREIBUNG
`type`	Erforderliches Attribut, es sei denn, Sie verweisen in der `sharedListeners`-Auflistung auf einen Listener. In diesem Fall müssen Sie nur anhand des Namens darauf verweisen (siehe Beispiel). Gibt den Typ des Listeners an. Sie müssen eine Zeichenfolge verwenden, die die unter Angeben vollqualifizierter Typnamen angegebenen Anforderungen erfüllt.
`initializeData`	Optionales Attribut. Die an den Konstruktor für die angegebene Klasse übergebene Zeichenfolge. Eine ConfigurationException wird ausgelöst, wenn die Klasse keinen Konstruktor hat, der eine Zeichenfolge akzeptiert.
`name`	Optionales Attribut. Gibt den Namen des Listeners an.
`traceOutputOptions`	Optionales Attribut. Gibt den TraceOutputOptions-Eigenschaftswert für den Ablaufverfolgungslistener an.
[benutzerdefinierte Attribute]	Optionale Attribute. Gibt den Wert für listenerspezifische Attribute an, die von der GetSupportedAttributes-Methode für diesen Listener identifiziert werden. Delimiter ist ein Beispiel für ein zusätzliches Attribut, das für die DelimitedListTraceListener-Klasse eindeutig ist.

Untergeordnete Elemente

Element	BESCHREIBUNG
<filter>	Fügt einen Filter zu einem Listener in der `Listeners`-Sammlung für eine Ablaufverfolgungsquelle hinzu.

Übergeordnete Elemente

Element	BESCHREIBUNG
`configuration`	Das Stammelement in jeder von den Common Language Runtime- und .NET Framework-Anwendungen verwendeten Konfigurationsdatei.
`system.diagnostics`	Gibt Ablaufverfolgungslistener an, die Meldungen sammeln, speichern und weiterleiten sowie die Ebene, für die ein Ablaufverfolgungsschalter festgelegt ist.
`sources`	Enthält die Ablaufverfolgungsquellen, die die Ablaufverfolgungsmeldungen initiieren.
`source`	Gibt eine Ablaufverfolgungsquelle an, die die Ablaufverfolgungsmeldungen initiiert.
`listeners`	Gibt Listener an, die Meldungen sammeln, speichern und weiterleiten.

Bemerkungen

Die listener-Klassen, die mit dem .NET Framework ausgeliefert werden, werden von der TraceListener-Klasse abgeleitet.

Wenn Sie das name-Attribut des Ablaufverfolgungslisteners nicht angeben, wird die Name-Eigenschaft des Ablaufverfolgungslisteners standardmäßig auf eine leere Zeichenfolge („“) festgelegt. Wenn Ihre Anwendung nur über einen Listener verfügt, können Sie ihn hinzufügen, ohne einen Namen anzugeben, und Sie können ihn entfernen, indem Sie eine leere Zeichenfolge als Namen angeben. Wenn Ihre Anwendung jedoch über mehr als einen Listener verfügt, sollten Sie einen eindeutigen Namen für jeden Ablaufverfolgungslistener angeben, was es Ihnen erlaubt, einzelne Ablaufverfolgungslistener in der TraceSource.Listeners-Auflistung zu identifizieren und zu verwalten.

Hinweis

Das Hinzufügen von mehr als einem Ablaufverfolgungslistener desselben Typs und mit demselben Namen führt dazu, dass der Listeners-Auflistung nur ein Ablaufverfolgungslistener dieses Typs und Namens hinzugefügt wird. Sie können der Listeners-Auflistung jedoch programmgesteuert mehrere identische Listener hinzufügen.

Der Wert für das initializeData-Attribut hängt vom Typ des Listeners ab, den Sie erstellen. Nicht alle Ablaufverfolgungslistener erfordern, dass Sie initializeData angeben.

Hinweis

Wenn Sie das initializeData-Attribut verwenden, wird möglicherweise die Compilerwarnung „Das Attribut ‚initializeData‘ ist nicht deklariert.“ angezeigt. Diese Warnung tritt auf, weil die Konfigurationseinstellungen gegen die abstrakte 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 verfügen, der einen Parameter akzeptiert.

Die folgende Tabelle zeigt die Ablaufverfolgungslistener, die im .NET Framework enthalten sind, und beschreibt den Wert ihrer initializeData-Attribute.

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. 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 der EventSchemaTraceListener schreibt.
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

Das folgende Beispiel zeigt, wie Sie mithilfe von <add>-Elementen die Listener console und textListener der Listeners-Auflistung für die Ablaufverfolgungsquelle TraceSourceApp hinzufügen. 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>

Share via