Definieren von Ereignisdatenvorlagen

Anbieter verwenden Datenvorlagen, um die ereignisspezifischen Daten zu definieren, die sie in einem Ereignis enthalten, und um die Filterdaten zu definieren, die eine ETW-Ablaufverfolgungssitzung an den Anbieter übergeben kann, wenn der Anbieter aktiviert wird. Wenn das Ereignis keine ereignisspezifischen Daten enthält, definieren Sie keine Vorlage. Verwenden Sie zum Definieren einer Vorlage das Template-Element . Eine Vorlage enthält ein Datenelement für jedes Datenelement, das der Anbieter in das Ereignis einschließt. Sie können integrale Typen, Zeichenfolgen, Arrays und Strukturen angeben. Sie müssen die Ereignisdaten in der Reihenfolge schreiben, in der die Datenelemente in der Vorlage definiert wurden.

Sie können auch ein XML-Fragment in die Vorlage einschließen, das Consumer verwenden sollten, um zu bestimmen, wie die Ereignisdaten gerendert werden sollen. Wenn Sie das Fragment nicht einschließen, sollten Consumer die Ereignisdaten in der Reihenfolge rendern, in der die Datenelemente in der Vorlage definiert wurden.

Wenn Sie eine Vorlage definieren, müssen Sie ihr einen Vorlagenbezeichner geben, mit dem Sie in einer Ereignisdefinition auf die Vorlage verweisen. Jedes Datenelement in der Vorlage muss einen Namen und einen Eingabedatentyp angeben (eine Liste der Eingabetypen finden Sie im Abschnitt Hinweise des komplexen InputType-Typs ). Wenn der Eingabedatentyp in mehreren Formaten gerendert werden kann, sollten Sie den Ausgabedatentyp angeben, der den Consumern mitteilt, wie das Datenelement gerendert werden soll. Beispielsweise kann ein UInt32-Eingabedatentyp unter anderem als ganze Zahl ohne Vorzeichen, Threadbezeichner, IPv4-Adresse und Win32-Fehlercode gerendert werden. Wenn Sie den Ausgabedatentyp nicht angeben, sollten Consumer den Standardausgabetyp des Eingabetyps verwenden, um das Datenelement zu rendern.

Um ein Array anzugeben, schließen Sie das count-Attribut in das Datenelement ein, und legen Sie es auf die Anzahl der Elemente im Array fest. Das Array kann ein Array mit variabler Größe oder ein Array mit fester Größe sein. Wenn das Array ein Array mit fester Größe ist, legen Sie count auf die Größe des Arrays fest. Wenn beispielsweise ein Array von ganzen Zahlen eine feste Größe von 10 hat, legen Sie count auf 10 fest. Wenn Sie das Array schreiben, müssen Sie 40 Byte Daten schreiben.

Wenn das Array ein Array mit variabler Größe ist, legen Sie count auf den Namen des Datenelements fest, das die Größe des Arrays enthält. Wenn das Array Zeiger enthält, wird die Adresse der Zeiger als Ereignisdaten geschrieben, nicht die Daten, auf die die Zeiger zeigen.

Sie müssen das Length-Attribut angeben, wenn es sich bei dem Datenelement um ein binäres Blob handelt. Sie können auch das Length-Attribut für Zeichenfolgen mit fester Länge angeben.

Geben Sie das Zuordnungsattribut an, wenn das Datenelement einen Enumerationswert darstellt und der Consumer anstelle des Werts selbst eine Zeichenfolge für den Wert ausgeben soll.

Wenn Sie Strukturen in die Vorlage einschließen, sollten Sie die Member der -Struktur einzeln schreiben, anstatt die -Struktur zu schreiben, es sei denn, Sie können die Ausrichtung der 8-Byte-Begrenzung garantieren.

Sie sollten die Informationen, die Sie in die Ereignisse einschließen, sorgfältig berücksichtigen, insbesondere wenn die Ereignisse in die globalen Kanäle geschrieben werden. In der Regel sollten Sie keine privaten Informationen in die Ereignisse einbeziehen. Dies schließt Klartextkennwörter und persönliche Benutzerinformationen ein. Darüber hinaus sollten Programme, die vom Benutzer ausgeführt werden, URLs, die der Benutzer besucht hat, und andere Informationen im Zusammenhang mit den Benutzeraktivitäten auf dem Computer als privat betrachtet werden.

Wenn Sie URLs und Benutzernamen in den Ereignissen aufzeichnen müssen, schreiben Sie diese nicht in die Windows-Kanäle (System und Anwendung), da diese Kanäle von allen authentifizierten Benutzern gelesen werden können. Schreiben Sie sie stattdessen in Ihre eigenen operativen oder analytischen Kanäle. Legen Sie die Zugriffsberechtigungen für diese Kanäle fest, damit nur Administratoren die Ereignisse lesen können. Möglicherweise müssen Sie eine entsprechende Offenlegung bereitstellen, um Die Benutzer darüber zu informieren, dass den Administratoren private Informationen zur Verfügung gestellt werden.

Im folgenden Beispiel wird gezeigt, wie eine Vorlage definiert wird. Sie müssen das tid-Attribut der Vorlage angeben, auf das Sie in der Ereignis- oder Filterdefinition verweisen.

<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 name="Microsoft-Windows-SampleProvider"
                guid="{1db28f2e-8f80-4027-8c5a-a11f7f10f62d}"
                symbol="PROVIDER_GUID"
                resourceFileName="<path to the exe or dll that contains the metadata resources>"
                messageFileName="<path to the exe or dll that contains the string resources>"
                message="$(string.Provider.Name)">

                . . .

                <maps>
                    <valueMap name="TransferType">
                        <map value="1" message="$(string.TransferType.Download)"/>
                        <map value="2" message="$(string.TransferType.Upload)"/>
                        <map value="3" message="$(string.TransferType.UploadReply)"/>
                    </valueMap>
                    <bitMap name="DaysOfTheWeek">
                        <map value="0x1" message="$(string.DaysOfTheWeek.Sunday)"/>
                        <map value="0x2" message="$(string.DaysOfTheWeek.Monday)"/>
                        <map value="0x4" message="$(string.DaysOfTheWeek.Tuesday)"/>
                        <map value="0x8" message="$(string.DaysOfTheWeek.Wednesday)"/>
                        <map value="0x10" message="$(string.DaysOfTheWeek.Thursday)"/>
                        <map value="0x20" message="$(string.DaysOfTheWeek.Friday)"/>
                        <map value="0x40" message="$(string.DaysOfTheWeek.Saturday)"/>
                    </bitMap>
                </maps>

                <templates>
                    <template tid="t2">
                        <data name="TransferName" inType="win:UnicodeString"/>
                        <data name="Day" inType="win:UInt32" map="DaysOfTheWeek"/>
                        <data name="Transfer" inType="win:UInt32" map="TransferType"/>
                    </template>

                    <template tid="t3">
                        <data name="TransferName" inType="win:UnicodeString"/>
                        <data name="ErrorCode" inType="win:Int32" outType="win:HResult"/>
                        <data name="FilesCount" inType="win:UInt16" />
                        <data name="Files" inType="win:UnicodeString" count="FilesCount"/>
                        <data name="BufferSize" inType="win:UInt32" />
                        <data name="Buffer" inType="win:Binary" length="BufferSize"/>
                        <data name="Certificate" inType="win:Binary" length="11" />
                        <data name="IsLocal" inType="win:Boolean" />
                        <data name="Path" inType="win:UnicodeString" />
                        <data name="ValuesCount" inType="win:UInt16" />
                        <struct name="Values" count="ValuesCount" >
                            <data name="Value" inType="win:UInt16" />
                            <data name="Name" inType="win:UnicodeString" />
                        </struct>
                    </template>
                </templates>

                . . .

            </provider>
        </events>
    </instrumentation>

    <localization>
        <resources culture="en-US">
            <stringTable>
                <string id="Provider.Name" value="Sample Provider"/>
                <string id="TransferType.Download" value="Download"/>
                <string id="TransferType.Upload" value="Upload"/>
                <string id="TransferType.UploadReply" value="Upload-reply"/>
                <string id="DaysOfTheWeek.Sunday" value="Sunday"/>
                <string id="DaysOfTheWeek.Monday" value="Monday"/>
                <string id="DaysOfTheWeek.Tuesday" value="Tuesday"/>
                <string id="DaysOfTheWeek.Wednesday" value="Wednesday"/>
                <string id="DaysOfTheWeek.Thursday" value="Thursday"/>
                <string id="DaysOfTheWeek.Friday" value="Friday"/>
                <string id="DaysOfTheWeek.Saturday" value="Saturday"/>
            </stringTable>
        </resources>
    </localization>

</instrumentationManifest>