Практическое руководство. Создание, инициализация и настройка переключателей трассировки

Примечание.

Эта статья относится к .NET Framework. Он не применяется к более новым реализациям .NET, включая .NET 6 и более поздние версии.

Переключатели трассировки позволяют включать, отключать и фильтровать выходные данные трассировки.

Создание и инициализация переключателей трассировки

Чтобы использовать переключатели трассировки, необходимо сначала создать их и разместить в коде. Существуют два предварительно определенных класса, с помощью которых можно создавать объекты переключателей: System.Diagnostics.BooleanSwitch и System.Diagnostics.TraceSwitch. Класс BooleanSwitch используется, когда требуется определить лишь факт отображения сообщений трассировки; если необходимо различать уровни трассировки, используется класс TraceSwitch. При использовании класса TraceSwitch можно определить собственные сообщения отладки и связать их с различными уровнями трассировки. Оба типа переключателей можно использовать как с трассировкой, так и с отладкой. По умолчанию класс BooleanSwitch отключен, а класс TraceSwitch имеет значение TraceLevel.Off. Переключатели трассировки можно создавать и помещать в любую часть кода, которая может их использовать.

Хотя допускается настройка уровней трассировки и других параметров конфигурации непосредственно в коде, для управления состоянием переключателей рекомендуется использовать файл конфигурации. Управление настройкой параметров в системе конфигурации обеспечивает большую гибкость — возможность включать и отключать различные переключатели и изменять уровни без перекомпиляции приложения.

Создание и инициализация переключателя трассировки

1. Определите тип переключателя (System.Diagnostics.BooleanSwitch или System.Diagnostics.TraceSwitch) и задайте его имя и описание.

2. Настройте переключатель трассировки. Дополнительные сведения см. в разделе Настройка переключателей трассировки.

   Следующий код создает два переключателя, по одному для каждого типа.

   Dim dataSwitch As New BooleanSwitch("Data", "DataAccess module")
   Dim generalSwitch As New TraceSwitch("General", "Entire application")
   

   System.Diagnostics.BooleanSwitch dataSwitch =
      new System.Diagnostics.BooleanSwitch("Data", "DataAccess module");
   System.Diagnostics.TraceSwitch generalSwitch =
      new System.Diagnostics.TraceSwitch("General",
      "Entire application");
   

Настройка переключателей трассировки

После распределения приложения можно по-прежнему включать или отключать вывод трассировки путем настройки в приложении переключателей трассировки. Настройка переключателя означает изменение его значения от внешнего источника после его инициализации. Можно изменить значения объектов переключателей с помощью файла конфигурации. Настройка переключателя трассировки выполняется для ее включения и отключения или для задания ее уровня, определяющего количество и тип сообщений, передаваемых в прослушиватели.

Настройка переключателей выполняется с помощью файла конфигурации. Для веб-приложения это файл Web.config, связанный с проектом. В приложении Windows этот файл называется (имя приложения).exe.config. В развернутом приложении этот файл должен находиться в той же папке, что и исполняемый файл.

Когда приложение выполняет код, который создает экземпляр переключателя в первый раз, оно проверяет в файле конфигурации сведения уровня трассировки для именованного переключателя. Система трассировки проверяет файл конфигурации для каждого конкретного переключателя только один раз — при первом создании переключателя приложением.

В развернутом приложении вы включаете код трассировки путем повторной настройки объектов переключателей, когда приложение не запущено. Обычно это подразумевает включение и отключение объектов переключателей или изменение уровней трассировки, а затем перезапуск приложения.

При создании экземпляра переключателя вы также инициализируете его, указывая два аргумента: displayName и description. Аргумент displayName конструктора устанавливает свойство Switch.DisplayName экземпляра класса Switch. Аргумент displayName — это имя, которое используется для настройки переключателя в файле .config, а аргумент description должен возвращать краткое описание переключателя и тип сообщений, которыми он управляет.

Помимо указания имени переключателя для настройки вы также должны указать значение для этого переключателя. Это значение представляет собой целое число. Для BooleanSwitch значение 0 соответствует значению Off (отключено), а любое ненулевое значение соответствует значению On (включено). Для TraceSwitch числа 0, 1, 2, 3 и 4 означают Off (отключено), Error (ошибка), Warning (предупреждение), Info (сведения) и Verbose (подробные сведения), соответственно. Любое число больше 4 интерпретируется как значение Verbose (подробно), а любое число меньше нуля — как значение Off (отключено).

Примечание.

В платформа .NET Framework версии 2.0 можно использовать текст для указания значения для коммутатора. Например, значение true для BooleanSwitch или текст, представляющий значение перечисления, такой как Error, для TraceSwitch. Строка <add name="myTraceSwitch" value="Error" /> эквивалентна <add name="myTraceSwitch" value="1" />.

Чтобы конечные пользователи могли настраивать переключатели трассировки приложения, вы должны предоставить подробную документацию по переключателям в своем приложении. Необходимо подробно описать, какие переключатели чем управляют и как их включать и отключать. Вы также должны предоставить конечному пользователю файл конфигурации с соответствующей справкой в комментариях.

Конфигурация коммутаторов трассировки

1. Чтобы использовать переключатели трассировки, необходимо сначала создать их в коде, как описано в разделе Создание и инициализация переключателя трассировки.

2. Если в проекте отсутствует файл конфигурации (app.config или Web.config), выберите Добавить новый элемент в меню Проект.

   • Visual Basic: в диалоговом окне Добавление нового элемента выберите элемент Файл конфигурации приложения.

     Файл конфигурации приложения создается и открывается. Это документ XML с корневым элементом <configuration>.

   • Visual C#: в диалоговом окне Добавление нового элемента выберите элемент XML-файл. Назовите файл app.config. В редакторе XML после объявления XML добавьте следующий XML-код:

     <configuration>
     </configuration>
     

     При компиляции проекта файл app.config копируется в выходную папку проекта и получает новое имя: имя_приложения.exe.config.

3. Добавьте соответствующий код XML для настройки переключателей между тегами <configuration> и </configuration>. В следующих примерах приведены переключатели BooleanSwitch (со свойством DisplayName, равным DataMessageSwitch) и TraceSwitch (со свойством DisplayName, равным TraceLevelSwitch).

   <system.diagnostics>
      <switches>
         <add name="DataMessagesSwitch" value="0" />
         <add name="TraceLevelSwitch" value="0" />
      </switches>
   </system.diagnostics>
   

   В данной конфигурации оба переключателя отключены.

4. Если необходимо включить переключатель BooleanSwitch, например DataMessagesSwitch в предыдущем примере, измените свойство Value на любое целое число, отличное от 0.

5. Если необходимо включить переключатель TraceSwitch, например TraceLevelSwitch в предыдущем примере, измените свойство Value на подходящее значение уровня (от 1 до 4).

6. Добавьте комментарии в файл конфигурации, чтобы конечный пользователь имел четкое представление, какие значения следует изменять для соответствующей настройки переключателей.

   В следующем примере показано, как может выглядеть окончательный код, включая комментарии:

   <system.diagnostics>
      <switches>
         <!-- This switch controls data messages. In order to receive data
            trace messages, change value="0" to value="1" -->
         <add name="DataMessagesSwitch" value="0" />
         <!-- This switch controls general messages. In order to
            receive general trace messages change the value to the
            appropriate level. "1" gives error messages, "2" gives errors
            and warnings, "3" gives more detailed error information, and
            "4" gives verbose trace information -->
         <add name="TraceLevelSwitch" value="0" />
      </switches>
   </system.diagnostics>
   

См. также

• Трассировка и инструментирование приложений
• Практическое руководство. Добавление операторов трассировки в код приложения
• Переключатели трассировки
• Схема параметров трассировки и отладки