Schreiben eines Instrumentierungsmanifests

Anwendungen und DLLs verwenden ein Instrumentierungsmanifest, um ihre Instrumentierungsanbieter und die Ereignisse zu identifizieren, die die Anbieter schreiben. Ein Manifest ist eine XML-Datei, die die Elemente enthält, die Ihren Anbieter identifizieren. Die Konvention besteht darin, .man als Erweiterung für Ihr Manifest zu verwenden. Das Manifest muss dem XSD-Ereignismanifest entsprechen. Ausführliche Informationen zum Schema finden Sie unter EventManifest-Schema.

Ein Instrumentierungsanbieter ist eine Anwendung oder DLL, die die Funktionen EventWriteEx, EventWriteString oder EventWriteTransfer aufruft, um Ereignisse in eine ETW-Ablaufverfolgungssitzung ( Event Tracing ) oder einen Ereignisprotokollkanal zu schreiben. Eine Anwendung kann einen einzelnen Instrumentierungsanbieter definieren, der alle ereignisse abdeckt, die sie schreibt, oder sie kann einen Anbieter für die Anwendung und einen Anbieter für jede ihrer DLLs definieren. Die Anzahl der Anbieter, die die Anwendung im Manifest definiert, hängt ausschließlich davon ab, wie die Anwendung die ereignisse organisieren möchte, die sie schreibt.

Der Vorteil der Angabe eines Anbieters für jede DLL besteht darin, dass Sie dann die einzelnen Anbieter und damit die von ihnen generierten Ereignisse aktivieren und deaktivieren können. Dieser Vorteil gilt nur, wenn der Anbieter durch eine ETW-Ablaufverfolgungssitzung aktiviert ist. Alle Ereignisse, die einen Ereignisprotokollkanal angeben, werden immer in diesen Kanal geschrieben.

Das Manifest muss den Anbieter und die ereignisse identifizieren, die es schreibt, aber die anderen Metadaten wie Kanäle, Ebenen und Schlüsselwörter sind optional. ob Sie die optionalen Metadaten definieren, hängt davon ab, wer die Ereignisse nutzt. Wenn Beispielsweise Administratoren oder Supportmitarbeiter die Ereignisse mithilfe eines Tools wie dem Windows-Ereignisanzeige nutzen, das Ereignisse aus Ereignisprotokollkanälen liest, müssen Sie die Kanäle definieren, in die die Ereignisse geschrieben werden. Wenn der Anbieter jedoch nur durch eine ETW-Ablaufverfolgungssitzung aktiviert wird, müssen Sie keine Kanäle definieren.

Obwohl die Metadaten für Ebenen, Aufgaben, Opcodes und Schlüsselwörter optional sind, sollten Sie sie verwenden, um die Ereignisse logisch zu gruppieren oder zu bucketen. Das Gruppieren der Ereignisse hilft den Consumern, nur die ereignisse zu nutzen, die von Interesse sind. Der Consumer könnte beispielsweise alle Ereignisse abfragen, bei denen die Ebene "kritisch" und Schlüsselwort (keyword) "Schreibzugriff" ist, oder alle Ereignisse abfragen, die von einer bestimmten Aufgabe geschrieben wurden.

Zusätzlich zu Consumern, die Ebene und Schlüsselwörter verwenden, um bestimmte Arten von Ereignissen zu nutzen, kann eine ETW-Ablaufverfolgungssitzung die Ebene und Schlüsselwort (keyword) Metadaten verwenden, um ETW anweisen, die Ereignisse zu beschränken, die in das Ereignisablaufverfolgungsprotokoll geschrieben werden. Beispielsweise könnte die Sitzung die Ereignisse auf nur Ereignisse beschränken, bei denen die Ebene "fehler" oder "kritisch" ist und Schlüsselwort (keyword) "gelesen" ist.

Ein Anbieter kann Filter definieren, die eine Sitzung verwendet, um die Ereignisse basierend auf Ereignisdaten zu filtern. Mit Ebene und Schlüsselwörtern bestimmt ETW, ob das Ereignis in das Protokoll geschrieben wird, aber mit Filtern verwendet der Anbieter die Filterdatenkriterien, um zu bestimmen, ob er das Ereignis in diese Sitzung schreibt. Die Filter sind nur anwendbar, wenn eine ETW-Ablaufverfolgungssitzung Ihren Anbieter aktiviert.

In den folgenden Abschnitten wird gezeigt, wie die Komponenten des Manifests definiert werden:

• Identifizieren des Anbieters
• Definieren der Kanäle, in die die Ereignisse geschrieben werden
• Definieren der Schweregrade von Ereignissen, die der Anbieter schreibt
• Definieren der Aufgaben und Vorgänge, die Ihr Anbieter ausführt
• Definieren der Schlüsselwörter, die die ereignisse klassifizieren, die der Anbieter schreibt
• Definieren der Filter, die der Anbieter zum Filtern der ereignisse verwendet, die er schreibt
• Definieren des Namens/Werts, auf den Ihre Vorlagendaten verweisen
• Definieren der Vorlagen, die die ereignisspezifischen Daten definieren
• Definieren der Ereignisse, die der Anbieter schreibt

Obwohl Sie ein Instrumentierungsmanifest manuell erstellen können, sollten Sie das ECManGen.exe-Tool verwenden, das im Ordner \Bin des Windows SDK enthalten ist. Das ECManGen.exe-Tool verwendet eine GUI, die Sie durch das Erstellen eines Manifests von Grund auf führt, ohne XML-Tags verwenden zu müssen. Wenn Sie sich mit den Informationen in diesem Abschnitt und im Abschnitt EventManifest-Schema vertraut machen, helfen Sie bei der Verwendung des Tools.

Wenn Sie Visual Studio als XML-Editor verwenden, können Sie dem Projekt das EventManifest-Schema hinzufügen (siehe XML-Menü), um Intellisense, die Inlineschemaüberprüfung und andere Features zu nutzen, um das Schreiben des Manifests einfach und präzise zu gestalten.

Nachdem Sie Ihr Manifest geschrieben haben, verwenden Sie den Nachrichtencompiler, um das Manifest zu überprüfen und die Ressourcen- und Headerdateien zu generieren, die Sie in Ihren Anbieter einschließen. Weitere Informationen finden Sie unter Kompilieren eines Instrumentierungsmanifests.

Das folgende Beispiel zeigt das Skelett eines vollständig definierten Ereignismanifests.

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