Menentukan Templat Data Peristiwa

Penyedia menggunakan templat data untuk menentukan data khusus peristiwa yang disertakan dengan peristiwa dan untuk menentukan data filter yang dapat diteruskan sesi pelacakan ETW ke penyedia saat mengaktifkan penyedia. Jika peristiwa tidak menyertakan data khusus peristiwa, Anda tidak akan menentukan templat. Untuk menentukan templat, gunakan elemen templat . Templat menyertakan item data untuk setiap bagian data yang disertakan penyedia dengan peristiwa tersebut. Anda dapat menentukan jenis integral, string, array, dan struktur. Anda harus menulis data peristiwa dalam urutan item data ditentukan dalam templat.

Anda juga dapat menyertakan dalam templat, fragmen XML yang harus digunakan konsumen untuk menentukan cara merender data peristiwa. Jika Anda tidak menyertakan fragmen, konsumen harus merender data peristiwa dalam urutan item data ditentukan dalam templat.

Saat Anda menentukan templat, Anda harus memberinya pengidentifikasi templat yang Anda gunakan untuk mereferensikan templat dalam definisi peristiwa. Setiap item data dalam templat harus menentukan nama dan jenis data input (untuk daftar jenis input, lihat bagian Keterangan dari jenis kompleks InputType ). Jika jenis data input dapat dirender dalam beberapa format, Anda harus menentukan jenis data output yang memberi tahu konsumen cara merender item data. Misalnya, jenis data input UInt32 dapat dirender sebagai bilangan bulat yang tidak ditandatangani, pengidentifikasi utas, alamat IPv4, dan kode kesalahan Win32. Jika Anda tidak menentukan jenis data output, konsumen harus menggunakan jenis output default jenis input untuk merender item data.

Untuk menentukan array, sertakan atribut hitungan pada item data dan atur ke jumlah elemen dalam array. Array dapat berupa array ukuran variabel atau array ukuran tetap. Jika array adalah array ukuran tetap, atur hitungan ke ukuran array. Misalnya, jika array bilangan bulat memiliki ukuran tetap 10, atur jumlah ke 10. Saat Menulis array, Anda harus menulis 40 byte data.

Jika array adalah array ukuran variabel, atur hitungan ke nama item data yang berisi ukuran array. Jika array berisi penunjuk, alamat penunjuk ditulis sebagai data peristiwa, bukan data yang ditujukan oleh pointer.

Anda harus menentukan atribut panjang jika item data adalah blob biner. Anda juga dapat menentukan atribut panjang untuk string panjang tetap.

Tentukan atribut peta jika item data mewakili nilai enumerasi dan Anda ingin konsumen mencetak string untuk nilai tersebut alih-alih nilai itu sendiri.

Jika Anda menyertakan struktur dalam templat, Anda harus menulis anggota struktur satu per satu alih-alih menulis struktur kecuali Anda dapat menjamin perataan batas 8-byte.

Anda harus mempertimbangkan dengan cermat informasi yang Anda sertakan dalam peristiwa, terutama ketika peristiwa ditulis ke dalam saluran global. Sebagai aturan umum, Anda tidak boleh menyertakan informasi privat dalam peristiwa tersebut. Ini termasuk kata sandi teks biasa dan informasi pengguna pribadi. Selain itu, program yang dijalankan oleh pengguna, URL yang dikunjungi pengguna, dan informasi lain yang terkait dengan aktivitas pengguna di komputer harus dianggap privat.

Jika Anda harus merekam URL dan nama pengguna dalam peristiwa, jangan menulisnya ke saluran Windows (Sistem dan Aplikasi) karena saluran ini dapat dibaca oleh semua pengguna yang diautentikasi. Sebagai gantinya, tulis ke saluran Operasional atau Analitik Anda sendiri. Atur izin akses pada saluran ini untuk mengizinkan hanya administrator untuk membaca peristiwa. Anda mungkin perlu memberikan pengungkapan yang sesuai untuk memberi tahu pengguna tentang fakta bahwa informasi privat tersedia untuk administrator.

Contoh berikut menunjukkan cara menentukan templat. Anda harus menentukan atribut tid templat yang Anda referensikan dalam definisi peristiwa atau definisi filter.

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