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

Статья
11/16/2008

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

Добавляет прослушиватели в коллекцию sharedListeners. sharedListeners представляет собой коллекцию прослушивателей, на которую любой Элемент <source> или Элемент <trace> может ссылаться. По умолчанию прослушиватели в коллекции sharedListeners не помещаются в коллекцию Listeners. Они должны добавляться по именам в Элемент <source> или Элемент <trace>. Невозможно получить прослушиватели в коллекцию sharedListeners в коде во время выполнения.

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

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

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

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

Атрибуты

Атрибут	Описание
name	Обязательный атрибут. Указывает имя прослушивателя, который используется для добавления общего прослушивателя в коллекцию Listeners.
type	Обязательный атрибут. Задает тип прослушивателя. Строка должна отвечать требованиям, указанным в разделе Указание полных имен типов.
initializeData	Необязательный атрибут. Строка, передаваемая в конструктор для заданного класса.

name

Обязательный атрибут.

Указывает имя прослушивателя, который используется для добавления общего прослушивателя в коллекцию Listeners.

type

Обязательный атрибут.

Задает тип прослушивателя. Строка должна отвечать требованиям, указанным в разделе Указание полных имен типов.

initializeData

Необязательный атрибут.

Строка, передаваемая в конструктор для заданного класса.

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

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

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

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

Заметки

Классы прослушивателей поставляемые с .NET Framework выводятся из класса TraceListener. Значение для атрибута name используется для добавления общего прослушивателя в коллекцию Listeners для прослеживания или источника прослеживания. Значение атрибута initializeData зависит от типа создаваемого прослушивателя. Не всем прослушивателям требуется определение атрибута initializeData.

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

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

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

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

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

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

Пример

Следующий пример показывает, как использовать элементы <add> для добавления TextWriterTraceListenertextListener в коллекцию sharedListeners. 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>