Elemento <add> per <listeners> per <source>

Articolo
09/12/2008

Aggiornamento: novembre 2007

Consente di aggiungere un listener all'insieme Listeners per un'origine di analisi.

Elemento <Configuration>
  Elemento <system.diagnostics>
    Elemento <sources>
      Elemento <source>
        Elemento <listeners> per <trace>
          Elemento <add> per <listeners> per <source>

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

Attributi ed elementi

Nelle sezioni riportate di seguito vengono illustrati attributi, elementi figlio e padre.

Attributi

Attributo	Descrizione
type	Attributo obbligatorio. Specifica il tipo del listener. È necessario utilizzare una stringa che soddisfi i requisiti indicati in Specifica di nomi di tipo completi.
initializeData	Attributo facoltativo. Stringa passata al costruttore per la classe specificata. Viene generata un'eccezione ConfigurationException se la classe non dispone di un costruttore che accetta una stringa.
name	Attributo facoltativo. Specifica il nome del listener.
traceOutputOptions	Attributo facoltativo. Specifica il valore della proprietà TraceOutputOptions per il listener di analisi.
[attributi personalizzati]	Attributi facoltativi. Specifica il valore degli attributi specifici del listener identificati dal metodo GetSupportedAttributes per tale listener. La proprietà Delimiter rappresenta un esempio di attributo aggiuntivo univoco per la classe DelimitedListTraceListener.

Elementi figlio

Elemento	Descrizione
Elemento <filter> per <add> per <listeners> per <source>	Consente di aggiungere un filtro a un listener dell'insieme Listeners per un'origine di analisi.

Elementi padre

Elemento	Descrizione
configuration	È l'elemento di primo livello in ciascun file di configurazione utilizzato in Common Language Runtime e nelle applicazioni .NET Framework.
system.diagnostics	Consente di specificare listener di analisi per la raccolta, la memorizzazione e l'invio di messaggi, nonché il livello in cui viene impostata un'opzione di analisi.
sources	Contiene le origini di analisi che danno inizio ai messaggi di analisi.
source	Specifica un'origine di analisi che dà inizio ai messaggi di analisi.
listeners	Specifica i listener per la raccolta, l'archiviazione e l'invio di messaggi.

Note

Le classi di listener fornite con .NET Framework derivano dalla classe TraceListener.

Se non viene specificato l'attributo name del listener di analisi, l'impostazione predefinita della proprietà Name del listener di analisi sarà una stringa vuota (""). Se l'applicazione dispone di un solo listener, è possibile aggiungerlo senza specificarne il nome e rimuoverlo specificando per il nome una stringa vuota. Se invece l'applicazione dispone di più listener, è necessario specificare un nome univoco per ciascun listener di analisi, al fine di identificare e gestire singolarmente i listener di analisi nell'insieme TraceSource.Listeners.

Nota

L'aggiunta di più listener di analisi dello stesso tipo e con lo stesso nome implica l'aggiunta di un solo listener di analisi di tale tipo e con tale nome all'insieme Listeners. È tuttavia possibile aggiungere a livello di codice più listener identici all'insieme Listeners.

Il valore dell'attributo initializeData dipende dal tipo di listener creato. Non per tutti i listener di analisi è necessario specificare l'attributo initializeData.

Nota

Quando si utilizza l'attributo initializeData, è possibile ottenere l'avviso del compilatore "Attributo 'initializeData' non dichiarato". Questo avviso viene generato perché le impostazioni di configurazione vengono convalidate in base alla classe di base astratta TraceListener che non riconosce l'attributo initializeData. In genere, è possibile ignorare questo avviso per implementazioni del listener di analisi che presentano un costruttore che accetta un parametro.

Nella tabella riportata di seguito vengono elencati i listener di analisi inclusi in .NET Framework e viene fornita una descrizione del valore dei relativi attributi initializeData.

Classe di listener di analisi	Valore dell'attributo initializeData
System.Diagnostics.ConsoleTraceListener	Valore useErrorStream del costruttore ConsoleTraceListener. Impostare l'attributo initializeData su true per scrivere l'output di analisi e di debug nel flusso di errori standard. Impostarlo invece su false per scrivere nel flusso di output standard.
System.Diagnostics.DelimitedListTraceListener	Nome del file in cui DelimitedListTraceListener esegue operazioni di scrittura.
System.Diagnostics.EventLogTraceListener	Nome di un'origine del log eventi esistente.
System.Diagnostics.EventSchemaTraceListener	Nome del file in cui EventSchemaTraceListener esegue operazioni di scrittura.
System.Diagnostics.TextWriterTraceListener	Nome del file in cui TextWriterTraceListener esegue operazioni di scrittura.
System.Diagnostics.XmlWriterTraceListener	Nome del file in cui XmlWriterTraceListener esegue operazioni di scrittura.

File di configurazione

È possibile utilizzare questo elemento nei file di configurazione del computer (Machine.config) e dell'applicazione.

Esempio

Nell'esempio riportato di seguito viene illustrato come utilizzare elementi <add> per aggiungere i listener console e textListener all'insieme Listeners per l'origine di analisi TraceSourceApp. Il listener textListener scrive l'output di analisi nel file 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>