macro TRACELOGGING_DEFINE_PROVIDER (traceloggingprovider.h)

  • Articolo

Definisce un handle per un provider TraceLogging.

Sintassi

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

Parametri

[in] handleVariable

Nome da usare per l'handle del provider, usando le convenzioni di denominazione del componente per le variabili globali, ad esempio MyComponentLog o g_hMyProvider.

[in] providerName

Valore letterale stringa con il nome del provider TraceLogging. Questo nome deve essere specifico per l'organizzazione e il componente in modo che non sia in conflitto con i provider di altri componenti. Questa stringa di nome verrà inclusa all'interno di ogni evento ETW generato dal provider, quindi provare a usare un nome relativamente breve. Ad esempio, è possibile usare un nome come "MyCompany.MyComponent" o "MyCompany.MyOrganization.MyComponent".

Deve essere un valore letterale stringa. Non usare una variabile.

[in] providerId

GUID del controllo ETW per il provider, specificato come elenco delimitato da virgole di 11 interi tra parentesi. Ad esempio, il GUID {ce5fa4ea-ab00-5402-8b76-9f76ac858fb5} verrebbe espresso come (0xce5fa4ea,0xab00,0x5402,0x8b,0x76,0x9f,0x76,0xac,0x85,0x8f,0xb5).

Anche se è possibile usare qualsiasi GUID univoco per l'ID provider, Microsoft consiglia di usare un GUID generato dal nome del provider usando l'algoritmo di hash dei nomi ETW. Per informazioni sulla generazione dell'ID provider, vedere di seguito.

[in, optional] __VA_ARGS__

Parametri facoltativi per il provider. La maggior parte dei provider non deve specificare parametri facoltativi.

Per associare il provider a un gruppo di provider ETW, aggiungere la macro TraceLoggingOptionGroup per specificare il GUID del gruppo del provider. In caso contrario, non specificare __VA_ARGS__ parametri.

Valore restituito

nessuno

Osservazioni

Un provider TraceLogging è una connessione tramite cui gli eventi possono essere inviati a ETW. La TRACELOGGING_DEFINE_PROVIDER macro definisce un provider TraceLogging e crea un handle che può essere utilizzato per accedervi. Registra anche informazioni sul provider, ad esempio il nome e il GUID del provider.

Questa macro deve essere richiamata in un file con estensione c o .cpp per definire l'handle per un provider TraceLogging. Ad esempio, se il provider è denominato MyCompany.MyComponent e il GUID del controllo è {ce5fa4ea-ab00-5402-8b76-9f76ac858fb5} , definirei il provider aggiungendo il codice seguente a uno dei file con estensione c o .cpp nel componente:

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

La macro precedente TRACELOGGING_DEFINE_PROVIDER può essere considerata come la definizione di una g_hMyProvider costante dell'handle del provider, simile al codice seguente:

const TraceLoggingHProvider g_hMyProvider = ...;

L'handle risultante ha ambito del modulo e può essere usato ovunque all'interno del modulo EXE, DLL o SYS in cui è definito. Usare la macro TRACELOGGING_DECLARE_PROVIDER , ad esempio in un'intestazione, per inoltrare l'handle in modo che possa essere usata da altri file con estensione c o .cpp nel componente.

All'avvio dell'esecuzione di un componente, il provider sarà in uno stato non registrato. Tutti i tentativi di usarlo per generare eventi verranno ignorati automaticamente. Prima di poter rispondere a qualsiasi chiamata di scrittura, è necessario registrare il provider usando TraceLoggingRegister. Questa operazione viene in genere eseguita durante l'avvio del componente, ad esempio in main, wmain, DllMain(DLL_PROCESS_ATTACH)WinMain, o DriverEntry. All'arresto del componente annullare la registrazione del provider chiamando TraceLoggingUnregister.

Nota

L'handle del provider definito da TRACELOGGING_DEFINE_PROVIDER è limitato al modulo. L'handle può essere usato come necessario all'interno del file EXE, DLL o SYS, ma non deve essere usato all'esterno dell'ambito del modulo, ovvero non deve essere passato ad altre DLL nello stesso processo. Ogni file EXE, DLL o SYS deve usare il proprio handle del provider e deve eseguire il proprio register e annullare la registrazione. Nelle compilazioni di debug viene attivata un'asserzione se si tenta di scrivere usando un handle del provider da un altro modulo.

Nome provider e ID

ETW esegue il filtro e il routing degli eventi usando l'ID del provider (denominato anche GUID del provider o GUID di controllo). Ad esempio, se si dispone di un provider denominato MyCompany.MyComponent con ID {ce5fa4ea-ab00-5402-8b76-9f76ac858fb5} provider, è possibile avviare una traccia per acquisire eventi da questo provider usando un comando tracelog come tracelog -start MySessionName -f MySession.etl -guid #ce5fa4ea-ab00-5402-8b76-9f76ac858fb5.

Tutti i provider ETW sono identificati sia dal nome del provider che dall'ID provider. Sia il nome che l'ID devono essere univoci in modo che non siano in conflitto con altri provider. Inoltre, il nome e l'ID devono essere collegati: una volta usato un nome specifico con un ID specifico per un provider ETW, tale nome non deve essere usato con altri ID e tale ID non deve essere usato con altri nomi.

L'ID provider può essere qualsiasi GUID univoco, ad esempio generato usando lo guidgen strumento SDK o https://uuidgen.org. Tuttavia, invece di usare un GUID generato in modo casuale per l'ID provider, Microsoft consiglia di generare l'ID provider dal nome del provider usando l'algoritmo di hash dei nomi ETW descritto di seguito. Ciò offre diversi vantaggi: è più facile ricordare solo il nome; l'ID e il nome vengono collegati automaticamente; strumenti come tracelog, traceview, EventSource e WPR hanno un supporto speciale per i provider che usano GLI ID generati usando questo algoritmo.

Ad esempio, se si dispone di un provider denominato MyCompany.MyComponent con ID {ce5fa4ea-ab00-5402-8b76-9f76ac858fb5} provider, è possibile avviare una traccia per acquisire eventi da questo provider usando un comando tracelog come tracelog -start MySessionName -f MySession.etl -guid *MyCompany.MyComponent. Ciò funziona perché l'ID {ce5fa4ea-ab00-5402-8b76-9f76ac858fb5} provider è stato generato eseguendo l'hashing del nome MyCompany.MyComponentdel provider , quindi lo strumento tracefmt considera -guid *MyCompany.MyComponent equivalente a -guid #ce5fa4ea-ab00-5402-8b76-9f76ac858fb5.

È possibile usare PowerShell per ottenere l'ID provider per un nome di provider specifico usando l'algoritmo di hash dei nomi ETW tramite la classe EventSource :

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

Risultati:

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

In C#, l'algoritmo di hashing dei nomi ETW può essere implementato come segue:

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

Esempio

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

Requisiti

Requisito Valore
Client minimo supportato Windows Vista [app desktop | App UWP]
Server minimo supportato Windows Server 2008 [app desktop | App UWP]
Piattaforma di destinazione Windows
Intestazione traceloggingprovider.h

Vedi anche

TRACELOGGING_DECLARE_PROVIDER

TraceLoggingWrite