TRACELOGGING_DEFINE_PROVIDER makro (traceloggingprovider.h)

Artikel
03/09/2024

Menentukan handel untuk penyedia TraceLogging.

Sintaks

void TRACELOGGING_DEFINE_PROVIDER(
  [in]            handleVariable,
  [in]            providerName,
  [in]            providerId,
  [in, optional]  __VA_ARGS__
);

Parameter

[in] handleVariable

Nama yang digunakan untuk handel penyedia, menggunakan konvensi penamaan komponen Anda untuk variabel global, misalnya MyComponentLog atau g_hMyProvider.

[in] providerName

String harfiah dengan nama penyedia TraceLogging. Nama ini harus spesifik untuk organisasi dan komponen Anda sehingga tidak bertentang dengan penyedia dari komponen lain. String nama ini akan disertakan dalam setiap peristiwa ETW yang dihasilkan oleh penyedia, jadi cobalah untuk menggunakan nama yang relatif pendek. Misalnya, Anda dapat menggunakan nama seperti "MyCompany.MyComponent" atau "MyCompany.MyOrganization.MyComponent".

Ini harus berupa string harfiah. Jangan gunakan variabel.

[in] providerId

GUID Kontrol ETW untuk penyedia, ditentukan sebagai daftar 11 bilangan bulat yang dipisahkan koma dalam tanda kurung. Misalnya, GUID {ce5fa4ea-ab00-5402-8b76-9f76ac858fb5} akan dinyatakan sebagai (0xce5fa4ea,0xab00,0x5402,0x8b,0x76,0x9f,0x76,0xac,0x85,0x8f,0xb5).

Meskipun GUID unik apa pun dapat digunakan untuk ID penyedia, Microsoft merekomendasikan penggunaan GUID yang dihasilkan dari nama penyedia menggunakan algoritma hash nama ETW. Lihat di bawah ini untuk informasi tentang membuat ID penyedia.

[in, optional] __VA_ARGS__

Parameter opsional untuk penyedia. Sebagian besar penyedia tidak perlu menentukan parameter opsional apa pun.

Jika Anda ingin penyedia Anda dikaitkan dengan grup penyedia ETW, tambahkan makro TraceLoggingOptionGroup untuk menentukan GUID grup penyedia. Jika tidak, jangan tentukan parameter apa pun __VA_ARGS__ .

Nilai kembali

Tidak ada

Keterangan

Penyedia TraceLogging adalah koneksi tempat peristiwa dapat dikirim ke ETW. TRACELOGGING_DEFINE_PROVIDER Makro mendefinisikan penyedia TraceLogging dan membuat handel yang dapat digunakan untuk mengaksesnya. Ini juga merekam informasi penyedia seperti nama penyedia dan GUID.

Makro ini harus dipanggil dalam file .c atau .cpp untuk menentukan handel untuk penyedia TraceLogging. Misalnya, jika penyedia saya diberi nama MyCompany.MyComponent dan GUID kontrol maka {ce5fa4ea-ab00-5402-8b76-9f76ac858fb5} saya akan menentukan penyedia dengan menambahkan kode berikut ke salah satu file .c atau .cpp di komponen saya:

TRACELOGGING_DEFINE_PROVIDER( // defines g_hProvider
    g_hProvider, // Name of the provider handle
    "MyCompany.MyComponent", // Human-readable name for the provider
    // {ce5fa4ea-ab00-5402-8b76-9f76ac858fb5}
    (0xce5fa4ea,0xab00,0x5402,0x8b,0x76,0x9f,0x76,0xac,0x85,0x8f,0xb5));

Makro di atas TRACELOGGING_DEFINE_PROVIDER dapat dianggap sebagai mendefinisikan g_hMyProvider konstanta handel penyedia, mirip dengan kode seperti:

const TraceLoggingHProvider g_hMyProvider = ...;

Handel yang dihasilkan memiliki cakupan modul dan dapat digunakan di mana saja dalam modul EXE, DLL, atau SYS di mana ia didefinisikan. Gunakan makro TRACELOGGING_DECLARE_PROVIDER sesuai kebutuhan (misalnya di header) untuk mendeklarasikan handel agar dapat digunakan oleh file .c atau .cpp lain di komponen Anda.

Ketika komponen mulai berjalan, penyedia akan berada dalam status tidak terdaftar. Setiap upaya untuk menggunakannya untuk menghasilkan peristiwa akan diabaikan secara diam-diam. Sebelum dapat menanggapi panggilan tulis apa pun, Anda perlu mendaftarkan penyedia menggunakan TraceLoggingRegister. Ini biasanya dilakukan selama startup komponen, misalnya dalam main, , wmainWinMain, DllMain(DLL_PROCESS_ATTACH), atau DriverEntry. Pada penonaktifan komponen, batalkan pendaftaran penyedia dengan memanggil TraceLoggingUnregister.

Catatan

Handel penyedia yang ditentukan oleh TRACELOGGING_DEFINE_PROVIDER dilingkup ke modul. Handel dapat digunakan sesuai kebutuhan dalam file EXE, DLL, atau SYS, tetapi tidak boleh digunakan di luar cakupan modul, yaitu tidak boleh diteruskan ke DLL lain dalam proses yang sama. Setiap file EXE, DLL, atau SYS harus menggunakan handel penyedianya sendiri dan harus melakukan Register dan Unregister sendiri. Dalam build debug, pernyataan akan diaktifkan jika Anda mencoba menulis menggunakan handel penyedia dari modul lain.

Nama penyedia dan ID

ETW melakukan pemfilteran dan perutean peristiwa menggunakan ID penyedia (juga disebut GUID Penyedia atau GUID Kontrol). Misalnya, jika Anda memiliki penyedia bernama MyCompany.MyComponent dengan ID {ce5fa4ea-ab00-5402-8b76-9f76ac858fb5} penyedia maka Anda dapat memulai jejak untuk mengambil peristiwa dari penyedia ini menggunakan perintah tracelog seperti tracelog -start MySessionName -f MySession.etl -guid #ce5fa4ea-ab00-5402-8b76-9f76ac858fb5.

Semua penyedia ETW diidentifikasi dengan nama penyedia dan ID penyedia. Nama dan ID harus unik sehingga tidak bertentang dengan penyedia lain. Selain itu, nama dan ID harus ditautkan: setelah nama tertentu digunakan dengan ID tertentu untuk penyedia ETW, nama tersebut tidak boleh digunakan dengan ID lain dan ID tersebut tidak boleh digunakan dengan nama lain.

ID penyedia dapat berupa GUID unik apa pun, yang dihasilkan menggunakan guidgen alat SDK atau https://uuidgen.org. Namun, alih-alih menggunakan GUID yang dihasilkan secara acak untuk ID penyedia, Microsoft merekomendasikan untuk menghasilkan ID penyedia dari nama penyedia menggunakan algoritma hash nama ETW yang dijelaskan di bawah ini. Ini memberikan beberapa manfaat: lebih mudah untuk mengingat nama saja; ID dan nama secara otomatis ditautkan; alat seperti tracelog, traceview, EventSource, dan WPR memiliki dukungan khusus untuk penyedia yang menggunakan ID yang dihasilkan menggunakan algoritma ini.

Misalnya, jika Anda memiliki penyedia bernama MyCompany.MyComponent dengan ID {ce5fa4ea-ab00-5402-8b76-9f76ac858fb5} penyedia maka Anda dapat memulai jejak untuk mengambil peristiwa dari penyedia ini menggunakan perintah tracelog seperti tracelog -start MySessionName -f MySession.etl -guid *MyCompany.MyComponent. Ini berfungsi karena ID {ce5fa4ea-ab00-5402-8b76-9f76ac858fb5} penyedia dihasilkan dengan hash nama MyCompany.MyComponentpenyedia , sehingga alat tracefmt dianggap -guid *MyCompany.MyComponent setara -guid #ce5fa4ea-ab00-5402-8b76-9f76ac858fb5dengan .

Anda dapat menggunakan PowerShell untuk mendapatkan ID penyedia untuk nama penyedia tertentu menggunakan algoritma hash nama ETW melalui kelas EventSource :

[System.Diagnostics.Tracing.EventSource]::new("MyCompany.MyComponent").Guid

Hasil:

Guid
----
ce5fa4ea-ab00-5402-8b76-9f76ac858fb5

Dalam C#, algoritma hashing nama ETW dapat diimplementasikan sebagai berikut:

static Guid ProviderIdFromName(string name)
{
    var signature = new byte[] {
        0x48, 0x2C, 0x2D, 0xB2, 0xC3, 0x90, 0x47, 0xC8,
        0x87, 0xF8, 0x1A, 0x15, 0xBF, 0xC1, 0x30, 0xFB };
    var nameBytes = System.Text.Encoding.BigEndianUnicode.GetBytes(name.ToUpperInvariant());
    using (var sha1 = new System.Security.Cryptography.SHA1Managed())
    {
        sha1.TransformBlock(signature, 0, signature.Length, null, 0);
        sha1.TransformFinalBlock(nameBytes, 0, nameBytes.Length);
        var hash = sha1.Hash;
        Array.Resize(ref hash, 16);
        hash[7] = (byte)((hash[7] & 0x0F) | 0x50);
        return new Guid(hash);
    }
}

Contoh

#include <windows.h> // or <wdm.h> for kernel-mode.
#include <winmeta.h> // For event level definitions.
#include <TraceLoggingProvider.h>

TRACELOGGING_DEFINE_PROVIDER( // defines g_hProvider
    g_hProvider, // Name of the provider handle
    "MyCompany.MyComponent", // Human-readable name for the provider
    // {ce5fa4ea-ab00-5402-8b76-9f76ac858fb5}
    (0xce5fa4ea,0xab00,0x5402,0x8b,0x76,0x9f,0x76,0xac,0x85,0x8f,0xb5));

int main(int argc, char* argv[]) // or DriverEntry for kernel-mode.
{
    TraceLoggingRegister(g_hProvider);

    TraceLoggingWrite(
        g_hProvider,
        "MyEvent1",
        TraceLoggingLevel(WINEVENT_LEVEL_WARNING), // Levels defined in <winmeta.h>
        TraceLoggingKeyword(MyEventCategories), // Provider-defined categories
        TraceLoggingString(argv[0], "arg0"), // field name is "arg0"
        TraceLoggingInt32(argc)); // field name is implicitly "argc"

    TraceLoggingUnregister(g_hProvider);
    return 0;
}

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows Vista [aplikasi desktop \| Aplikasi UWP]
Server minimum yang didukung	Windows Server 2008 [aplikasi desktop \| Aplikasi UWP]
Target Platform	Windows
Header	traceloggingprovider.h

Lihat juga

TRACELOGGING_DECLARE_PROVIDER

TraceLoggingWrite

Bagikan melalui