Macro TraceLoggingChannel (traceloggingprovider.h)

Macro wrapper TraceLogging qui définit le canal de l’événement.

La plupart des événements TraceLogging n’ont pas besoin de modifier le canal par défaut de l’événement et ne doivent pas utiliser TraceLoggingChannel.

Syntaxe

void TraceLoggingChannel(
  [in]  eventChannel
);

Paramètres

[in] eventChannel

Canal dans lequel l’événement doit être journalisé. Il s’agit d’une valeur entière comprise entre 0 et 255.

Consultez EVENT_DESCRIPTOR pour plus d’informations sur le canal d’événements.

Valeur de retour

None

Remarques

TraceLoggingChannel(eventChannel) peut être utilisé comme paramètre pour l’appel d’une macro TraceLoggingWrite . La plupart des événements TraceLogging n’ont pas besoin de modifier le canal par défaut de l’événement et ne doivent pas utiliser TraceLoggingChannel.

Le paramètre eventChannel doit être une constante au moment de la compilation de 0 à 255. Si aucun arg n’est TraceLoggingChannel(n) fourni, le canal par défaut est 11 (WINEVENT_CHANNEL_TRACELOGGING), ce qui indique qu’il s’agit d’un événement TraceLogging normal. Si plusieurs TraceLoggingChannel(n) arguments sont fournis, la valeur du dernier TraceLoggingChannel(n) paramètre est utilisée.

Les canaux sont utilisés dans les scénarios de suivi d’événements avancés pour Windows (ETW). Il s’agit notamment de l’écriture dans des consommateurs d’événements définis par le système, tels que le journal des événements Windows.

TraceLogging et journal des événements

Dans la plupart des cas, les développeurs utilisent l’ETW basé sur un manifeste pour les événements qui doivent être enregistrés par le journal des événements. Le journal des événements est principalement destiné à collecter des événements de faible volume susceptibles d’être utiles à l’administrateur d’un système. L’ETW basé sur un manifeste fonctionne bien pour cela, car il prend en charge les événements organisés avec soin (tous les événements du composant sont décrits dans un seul fichier manifeste) et parce qu’il prend en charge les chaînes de message localisables qui peuvent aider l’administrateur à savoir comment réagir à l’événement.

Bien que les événements TraceLogging n’aient pas de chaînes de message et ne soient généralement pas organisés de manière centralisée, TraceLogging peut toujours être approprié pour certains scénarios de journal des événements. Par exemple, alors que les événements qui vont aux journaux Windows (application, sécurité, installation et système) doivent toujours avoir des chaînes de message localisées et doivent toujours être utiles à l’administrateur système, les événements enregistrés dans les journaux des applications et des services peuvent être plus techniques et enregistrer des informations de diagnostic. Lorsque vous écrivez dans les journaux des applications et des services, vous pouvez utiliser TraceLogging pour simplifier la gestion des événements journalisés.

L’utilisation d’événements TraceLogging avec le journal des événements Windows est similaire à l’utilisation d’événements basés sur un manifeste normal avec le journal des événements. Vous devez toujours créer et inscrire un manifeste pour définir le fournisseur et les canaux, mais vous n’avez pas besoin de définir les événements individuels dans le manifeste :

• Écrivez un manifeste ETW qui définit votre fournisseur et les canaux du journal des événements. Le fournisseur dans le manifeste doit utiliser le même nom de fournisseur et le même GUID de fournisseur (ID de fournisseur) que vous avez utilisé dans votre macro TRACELOGGING_DEFINE_PROVIDER . Le manifeste n’a pas besoin d’inclure <event> ou <template> des définitions, car les événements TraceLogging sont auto-décrits.
• Dans le processus de génération de votre composant, utilisez le compilateur de messages (MC.exe) à partir de SDK Windows 10.0.22621 ou version ultérieure pour compiler le manifeste. Cela génère les fichiers suivants :
  • ManifestName.h: en-tête C/C++ contenant des définitions constantes. Cela définit les constantes ChannelSymbol et ChannelSymbol_KEYWORD que vous devez utiliser dans vos événements TraceLogging. (Les noms réels des constantes seront différents pour chaque canal.)
  • ManifestName.rc: script du compilateur de ressources (RC.exe) qui ajoute les données BIN du manifeste à un fichier binaire (EXE, DLL ou SYS). Vous devez inclure ce script de ressource dans les ressources de l’un des fichiers binaires de votre composant.
  • ManifestNameTEMP.BIN, MSG00001.bin: manifeste des données BIN référencées par ManifestName.rc.
• #include le fichier généré ManifestName.h dans le code qui doit générer des événements TraceLogging. Cela définit les constantes ChannelSymbol et ChannelSymbol_KEYWORD .
  • Si vous avez spécifié l’attribut symbol sur la <channel> définition ou <importChannel> dans le manifeste, le nom de ChannelSymbol correspond à la valeur de votre attribut de symbole . Sinon, ChannelSymbol sera ProviderSymbol_CHANNEL_ChannelName (c’est-à-dire qu’il utilisera le symbole de votre <provider> élément et le nom de votre <channel> élément ou <importChannel> ).
  • Le nom de ChannelSymbol_KEYWORD est le nom de ChannelSymbol suivi de _KEYWORD.
  • La constante ChannelSymbol_KEYWORD est générée uniquement par MC.exe 10.0.22621 ou version ultérieure.
• Chaque événement TraceLogging qui doit accéder au journal des événements doit utiliserTraceLoggingChannel(ChannelSymbol), TraceLoggingKeyword(ChannelSymbol_KEYWORD)pour définir le canal et mot clé pour l’événement. Par exemple, si le symbole de mon canal est MY_CHANNEL, j’ajouterai TraceLoggingChannel(MY_CHANNEL), TraceLoggingKeyword(MY_CHANNEL_KEYWORD) en tant que paramètres à la TraceLoggingWrite macro pour l’événement.
• Pour que le journal des événements reconnaisse votre fournisseur, les informations de votre manifeste doivent être incluses dans les ressources d’un module (FICHIER DLL, EXE ou SYS) qui sera installé sur le système cible.
• Pour que le journal des événements reçoive des événements de votre fournisseur, vous devez inscrire votre manifeste sur le système cible à l’aide wevtutil im ManifestFile.man /rf:PathToModuleWithResources.dll de lors de l’installation du composant. Vous devez également annuler l’inscription de votre manifeste à l’aide wevtutil um ManifestFile.man de lors de la désinstallation du composant.

Exemple d’événement TraceLogging pour le journal des événements :

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

Des mots clés spécifiés par l’utilisateur supplémentaires peuvent être ajoutés aux événements si nécessaire, soit en utilisant plusieurs arguments TraceLoggingKeyword , soit en spécifiant plusieurs mots clés dans un seul argument TraceLoggingKeyword , par exemple TraceLoggingKeyword(MY_CHANNEL_KEYWORD | MY_OTHER_KEYWORD).

Configuration requise

Voir aussi

EVENT_DESCRIPTOR

TraceLoggingWrite

Macros du wrapper TraceLogging