TRACELOGGING_DEFINE_PROVIDER Makro (traceloggingprovider.h)

  • Artikel

Definiert ein Handle für einen TraceLogging-Anbieter.

Syntax

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

Parameter

[in] handleVariable

Der Name, der für das Handle des Anbieters unter Verwendung der Benennungskonventionen Ihrer Komponente für globale Variablen verwendet werden soll, z. B. MyComponentLog oder g_hMyProvider.

[in] providerName

Ein Zeichenfolgenliteral mit dem Namen des TraceLogging-Anbieters. Dieser Name sollte spezifisch für Ihre organization und Komponente sein, damit es nicht zu Konflikten mit Anbietern aus anderen Komponenten kommt. Diese Namenszeichenfolge wird in jedes vom Anbieter generierte ETW-Ereignis eingeschlossen. Versuchen Sie daher, einen relativ kurzen Namen zu verwenden. Sie können beispielsweise einen Namen wie "MyCompany.MyComponent" oder "MyCompany.MyOrganization.MyComponent"verwenden.

Hierbei muss es sich um ein Zeichenfolgenliteral handeln. Verwenden Sie keine Variable.

[in] providerId

Die ETW-Steuerelement-GUID für den Anbieter, die als durch Trennzeichen getrennte Liste mit 11 ganzen Zahlen in Klammern angegeben wird. Die GUID {ce5fa4ea-ab00-5402-8b76-9f76ac858fb5} wird beispielsweise als (0xce5fa4ea,0xab00,0x5402,0x8b,0x76,0x9f,0x76,0xac,0x85,0x8f,0xb5)ausgedrückt.

Während eine eindeutige GUID für die Anbieter-ID verwendet werden kann, empfiehlt Microsoft die Verwendung einer GUID, die aus dem Anbieternamen mithilfe des ETW-Namenshashingalgorithmus generiert wird. Informationen zum Generieren der Anbieter-ID finden Sie unten.

[in, optional] __VA_ARGS__

Optionale Parameter für den Anbieter. Die meisten Anbieter müssen keine optionalen Parameter angeben.

Wenn Ihr Anbieter einer ETW-Anbietergruppe zugeordnet werden soll, fügen Sie das Makro TraceLoggingOptionGroup hinzu, um die Gruppen-GUID des Anbieters anzugeben. Geben Sie andernfalls keine __VA_ARGS__ Parameter an.

Rückgabewert

Keine

Bemerkungen

Ein TraceLogging-Anbieter ist eine Verbindung, über die Ereignisse an ETW gesendet werden können. Das TRACELOGGING_DEFINE_PROVIDER Makro definiert einen TraceLogging-Anbieter und erstellt ein Handle, das für den Zugriff verwendet werden kann. Außerdem werden Anbieterinformationen wie der Name und die GUID des Anbieters aufgezeichnet.

Dieses Makro sollte in einer C- oder .cpp-Datei aufgerufen werden, um das Handle für einen TraceLogging-Anbieter zu definieren. Wenn beispielsweise mein Anbieter benannt MyCompany.MyComponent ist und die Steuerelement-GUID ist {ce5fa4ea-ab00-5402-8b76-9f76ac858fb5} , würde ich den Anbieter definieren, indem ich einer der C- oder .cpp-Dateien in meiner Komponente den folgenden Code hinzufübe:

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

Das obige TRACELOGGING_DEFINE_PROVIDER Makro kann als Definition einer g_hMyProvider Anbieterhandlekonstante betrachtet werden, ähnlich wie Code wie:

const TraceLoggingHProvider g_hMyProvider = ...;

Das resultierende Handle verfügt über Modulbereich und kann überall innerhalb des EXE-, DLL- oder SYS-Moduls verwendet werden, in dem es definiert ist. Verwenden Sie das TRACELOGGING_DECLARE_PROVIDER Makro nach Bedarf (z. B. in einem Header), um das Handle vorwärts zu deklarieren, damit es von anderen C- oder .cpp-Dateien in Ihrer Komponente verwendet werden kann.

Wenn eine Komponente ausgeführt wird, befindet sich der Anbieter in einem nicht registrierten Zustand. Alle Versuche, sie zum Generieren von Ereignissen zu verwenden, werden unbeaufsichtigt ignoriert. Bevor er auf Schreibaufrufe reagieren kann, müssen Sie den Anbieter mithilfe von TraceLoggingRegister registrieren. Dies geschieht in der Regel während des Komponentenstarts, z. B. in main, wmain, WinMain, DllMain(DLL_PROCESS_ATTACH)oder DriverEntry. Heben Sie beim Herunterfahren der Komponente die Registrierung des Anbieters auf, indem Sie TraceLoggingUnregister aufrufen.

Hinweis

Das von TRACELOGGING_DEFINE_PROVIDER definierte Anbieterhandle ist auf das Modul ausgerichtet. Das Handle kann nach Bedarf in der EXE-, DLL- oder SYS-Datei verwendet werden, sollte aber nicht außerhalb des Modulbereichs verwendet werden, d. h. es sollte nicht an andere DLLs im gleichen Prozess übergeben werden. Jede EXE-, DLL- oder SYS-Datei sollte ein eigenes Anbieterhandle verwenden und ihr eigenes Registrieren und Aufheben der Registrierung ausführen. In Debugbuilds wird eine Assertion ausgelöst, wenn Sie versuchen, mithilfe eines Anbieterhandles aus einem anderen Modul zu schreiben.

Anbietername und -ID

ETW führt Ereignisfilterung und Routing mithilfe der Anbieter-ID (auch als Anbieter-GUID oder Control-GUID bezeichnet) durch. Wenn Sie beispielsweise einen Anbieter mit dem Namen MyCompany.MyComponent mit der Anbieter-ID {ce5fa4ea-ab00-5402-8b76-9f76ac858fb5} haben, können Sie eine Ablaufverfolgung starten, um Ereignisse von diesem Anbieter mithilfe eines Ablaufverfolgungsbefehls wie zu tracelog -start MySessionName -f MySession.etl -guid #ce5fa4ea-ab00-5402-8b76-9f76ac858fb5erfassen.

Alle ETW-Anbieter werden sowohl durch den Anbieternamen als auch durch die Anbieter-ID identifiziert. Sowohl der Name als auch die ID müssen eindeutig sein, damit sie nicht mit anderen Anbietern in Konflikt stehen. Darüber hinaus sollten der Name und die ID verknüpft werden: Sobald ein bestimmter Name mit einer bestimmten ID für einen ETW-Anbieter verwendet wird, sollte dieser Name nicht mit einer anderen ID verwendet werden, und diese ID sollte nicht mit einem anderen Namen verwendet werden.

Die Anbieter-ID kann eine beliebige eindeutige GUID sein, z. B. eine, die mit dem guidgen SDK-Tool oder https://uuidgen.orggeneriert wird. Anstatt jedoch eine zufällig generierte GUID für die Anbieter-ID zu verwenden, empfiehlt Microsoft, die Anbieter-ID mithilfe des unten beschriebenen ETW-Namenshashingalgorithmus aus dem Anbieternamen zu generieren. Dies bietet mehrere Vorteile: Es ist einfacher, sich nur den Namen zu merken. die ID und der Name werden automatisch verknüpft; Tools wie tracelog, traceview, EventSource und WPR verfügen über besondere Unterstützung für Anbieter, die mit diesem Algorithmus generierte IDs verwenden.

Wenn Sie beispielsweise einen Anbieter mit dem Namen MyCompany.MyComponent mit der Anbieter-ID {ce5fa4ea-ab00-5402-8b76-9f76ac858fb5} haben, können Sie eine Ablaufverfolgung starten, um Ereignisse von diesem Anbieter mithilfe eines Ablaufverfolgungsbefehls wie zu tracelog -start MySessionName -f MySession.etl -guid *MyCompany.MyComponenterfassen. Dies funktioniert, da die Anbieter-ID {ce5fa4ea-ab00-5402-8b76-9f76ac858fb5} durch Hashing des Anbieternamens MyCompany.MyComponentgeneriert wurde, sodass das tracefmt-Tool als äquivalent zu -guid #ce5fa4ea-ab00-5402-8b76-9f76ac858fb5betrachtet-guid *MyCompany.MyComponent.

Sie können PowerShell verwenden, um die Anbieter-ID für einen bestimmten Anbieternamen mithilfe des ETW-Algorithmus namens-hashing über die EventSource-Klasse abzurufen:

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

Ergebnisse:

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

In C# kann der ETW-Name-Hashing-Algorithmus wie folgt implementiert werden:

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);
    }
}

Beispiele

#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;
}

Anforderungen

Anforderung Wert
Unterstützte Mindestversion (Client) Windows Vista [Desktop-Apps | UWP-Apps]
Unterstützte Mindestversion (Server) Windows Server 2008 [Desktop-Apps | UWP-Apps]
Zielplattform Windows
Kopfzeile traceloggingprovider.h

Weitere Informationen

TRACELOGGING_DECLARE_PROVIDER

TraceLoggingWrite