Прочитать на английском

Поделиться через

Написание манифеста инструментирования

  • Статья

Приложения и библиотеки DLL используют манифест инструментирования для определения поставщиков инструментирования и событий, которые они записывают. Манифест — это XML-файл, содержащий элементы, определяющие поставщика. Соглашение заключается в том, чтобы использовать .man в качестве расширения для манифеста. Манифест должен соответствовать XSD манифесту события. Дополнительные сведения о схеме см. в разделе Схема EventManifest.

Поставщик инструментирования — это любое приложение или библиотека DLL, которые вызывают функции EventWriteEx, EventWriteString или EventWriteTransfer для записи событий в сеанс трассировки событий (ETW) или канал журнала событий. Приложение может определить одного поставщика инструментирования, который охватывает все события, которые оно записывает, или может определить поставщика для приложения и поставщика для каждого из его библиотек DLL. Количество поставщиков, определяемых приложением в манифесте, зависит исключительно от того, как приложение хочет организовать события, которые оно записывает.

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

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

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

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

Поставщик может определить фильтры, которые сеанс использует для фильтрации событий на основе данных события. С помощью уровней и ключевых слов трассировка событий Windows определяет, записывается ли событие в журнал, но с помощью фильтров поставщик использует критерии данных фильтра, чтобы определить, записывает ли событие в этот сеанс. Фильтры применяются только в том случае, если ваш поставщик включает сеанс трассировки событий Windows.

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

Хотя манифест инструментирования можно создать вручную, рекомендуется использовать средство ECManGen.exe, входящее в папку \Bin пакета Windows SDK. Средство ECManGen.exe использует графический интерфейс, который поможет вам создать манифест с нуля без использования XML-тегов. Знание сведений, приведенных в этом разделе и в разделе Схема EventManifest , поможет при использовании средства.

Если вы используете Visual Studio в качестве редактора XML, вы можете добавить в проект схему EventManifest (см. меню XML), чтобы воспользоваться преимуществами Intellisense, встроенной проверки схемы и другими функциями, чтобы сделать написание манифеста простым и точным.

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

В следующем примере показана структура полностью определенного манифеста события.

XML 
<instrumentationManifest
    xmlns="http://schemas.microsoft.com/win/2004/08/events" 
    xmlns:win="http://manifests.microsoft.com/win/2004/08/windows/events"
    xmlns:xs="http://www.w3.org/2001/XMLSchema"
    >

    <instrumentation>
        <events>
            <provider ...>
                <channels>
                    <importChannel .../>
                    <channel .../>
                </channels>
                <levels>
                    <level .../>
                </levels>
                <tasks>
                    <task .../>
                </tasks>
                <opcodes>
                    <opcode .../>
                </opcodes>
                <keywords>
                    <keyword .../>
                </keywords>
                <filters>
                    <filter .../>
                </filters>
                <maps>
                    <valueMap ...>
                        <map .../>
                    </valueMap>
                    <bitMap ...>
                        <map .../>
                    </bitMap>
                </maps>
                <templates>
                    <template ...>
                        <data .../>
                        <UserData>
                            <!-- valid XML fragment -->
                        </UserData>
                    </template>
                </templates>
                <events>
                    <event .../>
                </events>
            </provider>
        </events>
    </instrumentation>

    <localization>
        <resources ...>
            <stringTable>
                <string .../>
            </stringTable>
        </resources>
    </localization>

</instrumentationManifest>