Macro TraceLoggingChannel (traceloggingprovider.h)

Articolo
03/03/2024

Macro wrapper TraceLogging che imposta il canale per l'evento.

La maggior parte degli eventi TraceLogging non deve modificare il canale predefinito dell'evento e non deve usare TraceLoggingChannel.

Sintassi

void TraceLoggingChannel(
  [in]  eventChannel
);

Parametri

[in] eventChannel

Canale a cui deve essere registrato l'evento. Valore intero compreso tra 0 e 255.

Per informazioni dettagliate sul canale eventi , vedere EVENT_DESCRIPTOR .

Valore restituito

nessuno

Osservazioni

TraceLoggingChannel(eventChannel) può essere usato come parametro per una chiamata di una macro TraceLoggingWrite . La maggior parte degli eventi TraceLogging non deve modificare il canale predefinito dell'evento e non deve usare TraceLoggingChannel.

Il parametro eventChannel deve essere una costante in fase di compilazione da 0 a 255. Se non viene specificato alcun TraceLoggingChannel(n) argomento, il canale predefinito è 11 (WINEVENT_CHANNEL_TRACELOGGING), a indicare che si tratta di un normale evento TraceLogging. Se vengono forniti più TraceLoggingChannel(n) argomenti, verrà usato il valore dell'ultimo TraceLoggingChannel(n) parametro.

I canali vengono usati in scenari ETW (Event Tracing for Windows) avanzati. Questi includono la scrittura in consumer di eventi definiti dal sistema, ad esempio il registro eventi di Windows.

Avviso

Se il provider verrà eseguito in Windows prima di Windows 10, non usare TraceLoggingChannel. Affinché un evento venga riconosciuto come compatibile con TraceLogging dai decodificatori di eventi, il canale deve essere impostato sul valore predefinito (11) oppure deve essere stato contrassegnato come evento TraceLogging dal runtime ETW durante EventWrite. Questo contrassegno eventi è abilitato chiamando EventSetInformation per configurare il provider come provider TraceLogging. EventSetInformation in Windows 10 o versione successiva abilita il supporto per gli eventi TraceLogging indipendentemente dal canale, ma le versioni precedenti di Windows richiedono un aggiornamento di Windows prima di supportare il contrassegno degli eventi TraceLogging. Per gli eventi acquisiti nei sistemi senza un EventSetInformation aggiornato, channel 11 è l'unico modo per riconoscere un evento TraceLogging, quindi gli eventi con altri canali potrebbero non decodificare correttamente.

TraceLogging e registro eventi

Nella maggior parte dei casi, gli sviluppatori usano ETW basati su manifesto per gli eventi che devono essere registrati dal registro eventi. Il registro eventi è destinato principalmente alla raccolta di eventi con volume ridotto che potrebbero essere utili per l'amministratore di un sistema. L'ETW basato su manifesto funziona correttamente perché supporta eventi accuratamente curati (tutti gli eventi per il componente sono descritti in un unico file manifesto) e perché supporta stringhe di messaggi localizzabili che consentono all'amministratore di sapere come reagire all'evento.

Anche se gli eventi TraceLogging non hanno stringhe di messaggio e in genere non sono curate centralmente, TraceLogging può comunque essere appropriato per alcuni scenari del registro eventi. Ad esempio, mentre gli eventi che passano ai log di Windows (applicazione, sicurezza, installazione e sistema) devono avere sempre stringhe di messaggi localizzate e devono essere sempre utili per l'amministratore di sistema, gli eventi registrati nei log applicazioni e servizi possono essere più tecnici e possono registrare informazioni di diagnostica. Quando si scrivono nei log delle applicazioni e dei servizi, è possibile usare TraceLogging per semplificare la gestione degli eventi registrati.

L'uso degli eventi TraceLogging con registro eventi di Windows è simile all'uso di normali eventi basati su manifesto con registro eventi. È comunque necessario creare e registrare un manifesto per definire il provider e i canali, ma non è necessario definire i singoli eventi nel manifesto:

Scrivere un manifesto ETW che definisce il provider e i canali del registro eventi. Il provider nel manifesto deve usare lo stesso nome del provider e lo stesso GUID del provider (ID provider) usato nella macro TRACELOGGING_DEFINE_PROVIDER . Il manifesto non deve includere <event> o <template> definizioni perché gli eventi TraceLogging sono autodescrittura.
Nel processo di compilazione per il componente usare il compilatore di messaggi (MC.exe) da Windows SDK 10.0.22621 o versione successiva per compilare il manifesto. Verranno generati i file seguenti:
- ManifestName.h: intestazione C/C++ contenente definizioni costanti. Verranno definite le costanti ChannelSymbol e le costanti ChannelSymbol_KEYWORD che sarà necessario usare negli eventi TraceLogging. I nomi effettivi delle costanti saranno diversi per ogni canale.
- ManifestName.rc: script del compilatore di risorse (RC.exe) che aggiunge i dati BIN del manifesto a un file binario (EXE, DLL o SYS). Sarà necessario includere questo script di risorsa nelle risorse di uno dei file binari nel componente.
- ManifestNameTEMP.BIN, MSG00001.bin: dati BIN manifesto a cui fa ManifestName.rcriferimento .
#include il file generato ManifestName.h nel codice che deve generare eventi TraceLogging. Verranno definite le costanti ChannelSymbol e ChannelSymbol_KEYWORD .
- Se è stato specificato l'attributo symbol nella <channel> definizione o <importChannel> nel manifesto, il nome di ChannelSymbol sarà il valore dell'attributo symbol . In caso contrario, ChannelSymbol sarà ProviderSymbol_CHANNEL_ChannelName (ad esempio, userà il simbolo dell'elemento <provider> e il nome dell'elemento <channel> o <importChannel> ).
- Il nome di ChannelSymbol_KEYWORD è il nome di ChannelSymbol seguito da _KEYWORD.
- La costante ChannelSymbol_KEYWORD viene generata solo dalla MC.exe versione 10.0.22621 o successiva.
Ogni evento TraceLogging da passare al registro eventi deve usareTraceLoggingChannel(ChannelSymbol), TraceLoggingKeyword(ChannelSymbol_KEYWORD) per impostare il canale e la parola chiave per l'evento. Ad esempio, se il simbolo del canale è MY_CHANNEL, aggiungerei TraceLoggingChannel(MY_CHANNEL), TraceLoggingKeyword(MY_CHANNEL_KEYWORD) come parametri alla TraceLoggingWrite macro per l'evento.
Affinché il registro eventi riconosca il provider, le informazioni del manifesto devono essere incluse nelle risorse di un modulo (FILE DLL, EXE o SYS) che verrà installato nel sistema di destinazione.
Affinché il registro eventi riceva gli eventi dal provider, è necessario registrare il manifesto nel sistema di destinazione usando wevtutil im ManifestFile.man /rf:PathToModuleWithResources.dll durante l'installazione del componente. È anche necessario annullare la registrazione del manifesto usando wevtutil um ManifestFile.man durante la disinstallazione del componente.

Importante

Se il provider è registrato nel registro eventi, tutti gli eventi generati dal provider devono avere una parola chiave diversa da zero specificata con TraceLoggingKeyword, anche se l'evento non è destinato al registro eventi. Gli eventi con parola chiave 0 non possono essere filtrati in modo efficiente e verranno recapitati al registro eventi solo per essere eliminati. Se il registro eventi è in ascolto di eventi dal provider, qualsiasi evento con parola chiave 0 aumenterà inutilmente il sovraccarico del registro eventi.

Esempio di evento TraceLogging per il registro eventi:

TraceLoggingWrite(
    g_hMyProvider,
    "MyWarningEventName",
    TraceLoggingChannel(MY_CHANNEL),         // constant from the MC-generated header
    TraceLoggingKeyword(MY_CHANNEL_KEYWORD), // constant from the MC-generated header
    TraceLoggingLevel(WINEVENT_LEVEL_WARNING), // Levels defined in <winmeta.h>
    TraceLoggingKeyword(MyEventCategories), // Additional keywords are ok.
    TraceLoggingHResult(errorCode, "Error"));

È possibile aggiungere altre parole chiave specificate dall'utente agli eventi, se appropriato, usando più argomenti TraceLoggingKeyword o specificando più parole chiave in un singolo argomento TraceLoggingKeyword , ad esempio TraceLoggingKeyword(MY_CHANNEL_KEYWORD | MY_OTHER_KEYWORD).

Requisiti

Requisito	Valore
Client minimo supportato	Windows 10 [solo app desktop]
Server minimo supportato	Windows Server 2012 R2
Piattaforma di destinazione	Windows
Intestazione	traceloggingprovider.h

Vedi anche

EVENT_DESCRIPTOR

TraceLoggingWrite

Macro wrapper TraceLogging

Condividi tramite