Элемент <add> для элемента <listeners> для элемента <source>

Обновлен: Ноябрь 2007

Добавляет прослушиватель в коллекцию Listeners для источника трассировки.

Элемент <configuration>
  Элемент <system.diagnostics>
    Элемент <sources>
      Элемент <source>
        Элемент <listeners> для элемента <trace>
          Элемент <add> для элемента <listeners> для элемента <source>

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

Атрибуты и элементы

В следующих разделах описаны атрибуты, дочерние и родительские элементы.

Атрибуты

Атрибут	Описание
type	Обязательный атрибут. Задает тип прослушивателя. Строка должна отвечать требованиям, указанным в разделе Указание полных имен типов.
initializeData	Необязательный атрибут. Строка, передаваемая в конструктор для заданного класса. Если класс не содержит конструктора, принимающего в качестве значения строковое выражение, происходит исключение ConfigurationException.
name	Необязательный атрибут. Указывает имя прослушивателя.
traceOutputOptions	Необязательный атрибут. Задает значение свойства TraceOutputOptions для прослушивателя трассировки.
[настраиваемые атрибуты]	Необязательные атрибуты. Определяет значение специфичных для прослушивателя атрибутов, идентифицируемых методом GetSupportedAttributes для данного прослушивателя. Delimiter — пример дополнительного атрибута, уникального для класса DelimitedListTraceListener.

Дочерние элементы

Элемент	Описание
Элемент <filter> для элемента <add> для элемента <listeners> для элемента <source>	Добавляет фильтр к прослушивателю в коллекции Listeners для источника трассировки.

Родительские элементы

Элемент	Описание
configuration	Корневой элемент в любом файле конфигурации, используемом средой CLR и приложениями .NET Framework.
system.diagnostics	Задает прослушиватели трассировки для сбора, хранения и маршрутизации сообщений, а также уровень, на котором установлен переключатель трассировки.
sources	Содержит источники трассировки, инициирующие сообщения трассировки.
source	Указывает источник трассировки, инициирующий сообщения трассировки.
listeners	Задает прослушивателей для сбора, хранения и маршрутизации сообщений.

Заметки

Классы прослушивателей, поставляемые с .NET Framework, являются производными от класса TraceListener.

Если атрибут name для прослушивателя трассировки не задан, в качестве значения свойства Name по умолчанию устанавливается пустая строка (""). Если у приложения имеется только один прослушиватель, его можно добавить без указания имени и удалить, указав в качестве имени пустую строку. Однако если у приложения более одного прослушивателя, следует задать для каждого из них уникальное имя, позволяющее идентифицировать отдельные прослушиватели трассировки и управлять ими в коллекции TraceSource.Listeners.

Примечание.
Добавление нескольких прослушивателей трассировки одного типа и с одним именем приводит к добавлению в коллекцию Listeners только одного прослушивателя указанного типа с указанным именем. Однако программными средствами можно добавить несколько идентичных прослушивателей в коллекцию Listeners.

Значение атрибута initializeData зависит от типа создаваемого прослушивателя. Не всем прослушивателям требуется определение атрибута initializeData.

Примечание.

При использовании атрибута initializeData возможно получение предупреждения компилятора "Атрибут "initializeData" не объявлен". Это предупреждение происходит из-за проверки параметров конфигурации относительно абстрактного базового класса TraceListener, который не распознает атрибут initializeData. Как правило, можно игнорировать это предупреждение для реализаций прослушивателя трассировки, имеющих конструктор, который принимает параметр.

Следующая таблица содержит перечень прослушивателей трассировки, входящих в комплект поставки .NET Framework, и описание значения их атрибутов initializeData.

Класс прослушивателей трассировки	Значение атрибута initializeData
System.Diagnostics.ConsoleTraceListener	Значение useErrorStream для конструктора ConsoleTraceListener. Задайте для атрибута initializeData значение "true", чтобы вести запись трассировки и отладку вывода в стандартный поток ошибок; задайте значение "false", чтобы вести запись в стандартный выходной поток.
System.Diagnostics.DelimitedListTraceListener	Имя файла, в который осуществляет запись объект DelimitedListTraceListener.
System.Diagnostics.EventLogTraceListener	Имя существующего источника журнала событий.
System.Diagnostics.EventSchemaTraceListener	Имя файла, в который осуществляет запись объект EventSchemaTraceListener.
System.Diagnostics.TextWriterTraceListener	Имя файла, в который осуществляет запись объект TextWriterTraceListener.
System.Diagnostics.XmlWriterTraceListener	Имя файла, в который осуществляет запись объект XmlWriterTraceListener.

Файл конфигурации

Этот элемент может быть использован в файле конфигурации компьютера (Machine.config) и в файле конфигурации приложения.

Пример

В следующем примере показано использование элементов <add> для добавления прослушивателей console и textListener в коллекцию Listeners для источника трассировки TraceSourceApp. Прослушиватель textListener записывает результат трассировки в файл 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> 

См. также

Основные понятия

Прослушиватели трассировки

Ссылки

Схема параметров трассировки и отладки

TraceSource

TraceListener