Как: Создать, инициализировать и настроить переключатели трассировки

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

Создание и инициализация коммутатора трассировки

Чтобы использовать коммутаторы трассировки, необходимо сначала создать их и поместить их в код. Существует два предопределенных класса, из которых можно создать объекты switch: 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");
   

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

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

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

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

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

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

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

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

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

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. После тега <configuration>, но перед тегом </configuration> добавьте соответствующий XML-код для конфигурации коммутаторов. В следующих примерах демонстрируется BooleanSwitch со свойством DisplayName и TraceSwitch со свойством DisplayName.

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

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

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

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

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

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

   <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>
   

См. также

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