Elemento <add> de <listeners> de <source>

Artículo
12/12/2008

Actualización: noviembre 2007

Agrega un agente de escucha a la colección Listeners de un origen de seguimiento.

<configuration> (Elemento)
  Elemento <system.diagnostics>
    <sources> (Elemento)
      <source> (Elemento)
        Elemento <listeners> para <trace>
          Elemento <add> de <listeners> de <source>

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

Atributos y elementos

En las siguientes secciones se describen los atributos, elementos secundarios y elementos primarios.

Atributos

Atributo	Descripción
type	Atributo necesario. Especifica el tipo del agente de escucha. Debe utilizar una cadena que cumpla los requisitos enumerados en Especificar nombres de tipo completos.
initializeData	Atributo opcional. Cadena pasada al constructor de la clase especificada. Si la clase no tiene un constructor que toma una cadena, se inicia una excepción ConfigurationException.
name	Atributo opcional. Especifica el nombre del agente de escucha.
traceOutputOptions	Atributo opcional. Especifica el valor de la propiedad TraceOutputOptions para el agente de escucha de seguimiento.
[atributos personalizados]	Atributos opcionales. Especifica el valor para los atributos específicos del agente de escucha identificados por el método GetSupportedAttributes de ese agente de escucha. Delimiter es un ejemplo de un atributo adicional único de la clase DelimitedListTraceListener.

Elementos secundarios

Elemento	Descripción
Elemento <filter> para <add> de <listeners> de <source>	Agrega un filtro a un agente de escucha de la colección Listeners para un origen de seguimiento.

Elementos primarios

Elemento	Descripción
configuration	Es el elemento raíz de cada archivo de configuración que utilizan las aplicaciones Common Language Runtime y .NET Framework.
system.diagnostics	Especifica los agentes de escucha de seguimiento que recopilan, almacenan y enrutan mensajes, y el nivel donde se establece un modificador de seguimiento.
sources	Contiene orígenes de seguimiento que inician mensajes de seguimiento.
source	Especifica un origen de seguimiento que inicia mensajes de seguimiento.
listeners	Especifica agentes de escucha que recopilan, almacenan y enrutan mensajes.

Comentarios

Las clases de agente de escucha incluidas en .NET Framework se derivan de la clase TraceListener.

Si no especifica el atributo name del agente de escucha de seguimiento, la propiedad Name del agente de escucha de seguimiento tiene como valor predeterminado una cadena vacía (""). Si su aplicación tiene sólo un agente de escucha, puede agregarlo sin especificar un nombre y quitarlo especificando una cadena vacía para el nombre. Sin embargo, si su aplicación tiene más de un agente de escucha, debe especificar un nombre único para cada agente de escucha de seguimiento, de forma que pueda identificar y administrar los agentes de escucha de seguimiento individualmente dentro de la colección TraceSource.Listeners.

Nota

Agregar más de un agente de escucha de seguimiento del mismo tipo y con el mismo nombre tiene como resultado que sólo se agregue a la colección Listeners un agente de escucha de seguimiento con ese tipo y nombre. Sin embargo, puede agregar mediante programación varios agentes de escucha idénticos a la colección Listeners.

El valor del atributo initializeData depende del tipo de agente de escucha que se cree. No todos los agentes de escucha de seguimiento requieren que se especifique initializeData.

Nota

Cuando se utiliza el atributo initializeData, puede que aparezca la advertencia del compilador "No se ha declarado el atributo 'initializeData'". Esta advertencia se produce porque los valores de configuración se validan con la clase base abstracta TraceListener, que no reconoce el atributo initializeData. Normalmente, se puede omitir esta advertencia para las implementaciones de agentes de escucha de seguimiento con un constructor que toma un parámetro.

En la tabla siguiente se muestran los agentes de escucha de seguimiento incluidos en .NET Framework y se describe el valor de sus atributos initializeData.

Clase de agente de escucha de seguimiento	Valor del atributo initializeData
System.Diagnostics.ConsoleTraceListener	El valor de useErrorStream para el constructor ConsoleTraceListener. Establezca el atributo initializeData en "true" para escribir los resultados del seguimiento y la depuración en la secuencia estándar de error; establézcalo en "false" para escribir en la secuencia estándar de salida.
System.Diagnostics.DelimitedListTraceListener	Nombre del archivo en el que escribe DelimitedListTraceListener.
System.Diagnostics.EventLogTraceListener	Nombre de un origen de registro de eventos existente.
System.Diagnostics.EventSchemaTraceListener	Nombre del archivo en el que escribe EventSchemaTraceListener.
System.Diagnostics.TextWriterTraceListener	Nombre del archivo en el que escribe TextWriterTraceListener.
System.Diagnostics.XmlWriterTraceListener	Nombre del archivo en el que escribe XmlWriterTraceListener.

Archivo de configuración

Este elemento se puede utilizar en el archivo de configuración del equipo (Machine.config) y en el archivo de configuración de la aplicación.

Ejemplo

El ejemplo siguiente muestra cómo utilizar elementos <add> para agregar los agentes de escucha console y textListener a la colección Listeners del origen de seguimiento TraceSourceApp. El agente de escucha textListener escribe el resultado del seguimiento en el archivo 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>