Элемент <add> для <listeners> для <trace>

Статья
08/11/2011

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

<add name="name" 
     type="trace listener class name, Version, Culture, PublicKeyToken"
     initializeData="data"/>

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

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

Атрибуты

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

type

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

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

initializeData

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

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

name,

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

Указывает имя прослушивателя.

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

Отсутствует.

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

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

Заметки

Классы Debug и Trace совместно используют коллекцию Listeners. Если в одном из этих классов в коллекцию добавляется объект прослушивателя, то этот прослушиватель используется и в другом классе. Классы прослушивателей являются производными от класса TraceListener.

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

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

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

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

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

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

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

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

Пример

В следующем примере показано, как использовать элементы <add> для добавления прослушивателей MyListener и MyEventListener в коллекцию Listeners. MyListener создает файл MyListener.log и записывает в него результат. MyEventListener создает запись в журнале событий.

<configuration>
   <system.diagnostics>
      <trace autoflush="true" indentsize="0">
         <listeners>
            <add name="myListener" type="System.Diagnostics.TextWriterTraceListener, system, version=1.0.3300.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" initializeData="c:\myListener.log" />
            <add name="MyEventListener"
                 type="System.Diagnostics.EventLogTraceListener, system, version=1.0.3300.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"                 initializeData="MyConfigEventLog"/>
            <add name="configConsoleListener"
                 type="System.Diagnostics.ConsoleTraceListener, system, version=1.0.3300.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"/>
         </listeners>
      </trace>
   </system.diagnostics>
</configuration>