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

Статья
08/11/2011

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

<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, и описание значения их атрибутов 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>