TraceLoggingChannel-Makro (traceloggingprovider.h)

  • Artikel

TraceLogging-Wrappermakro , das den Kanal für das Ereignis festlegt.

Die meisten TraceLogging-Ereignisse müssen den Standardkanal des Ereignisses nicht ändern und sollten nicht TraceLoggingChannel verwenden.

Syntax

void TraceLoggingChannel(
  [in]  eventChannel
);

Parameter

[in] eventChannel

Der Kanal, in dem das Ereignis protokolliert werden soll. Dies ist ein ganzzahliger Wert zwischen 0 und 255.

Ausführliche Informationen zum Ereigniskanal finden Sie unter EVENT_DESCRIPTOR .

Rückgabewert

Keine

Bemerkungen

TraceLoggingChannel(eventChannel) kann als Parameter für einen Aufruf eines TraceLoggingWrite-Makros verwendet werden. Die meisten TraceLogging-Ereignisse müssen den Standardkanal des Ereignisses nicht ändern und sollten nicht TraceLoggingChannel verwenden.

Der eventChannel-Parameter muss eine Kompilierzeitkonstante von 0 bis 255 sein. Wenn kein TraceLoggingChannel(n) Argument angegeben wird, ist der Standardkanal 11 (WINEVENT_CHANNEL_TRACELOGGING), was angibt, dass es sich um ein normales TraceLogging-Ereignis handelt. Wenn mehrere TraceLoggingChannel(n) Args angegeben werden, wird der Wert aus dem letzten TraceLoggingChannel(n) Parameter verwendet.

Kanäle werden in szenarien der erweiterten Ereignisablaufverfolgung für Windows (ETW) verwendet. Dazu gehört das Schreiben an systemdefinierte Ereignisconsumer wie das Windows-Ereignisprotokoll.

Warnung

Wenn Ihr Anbieter unter Windows vor Windows 10 ausgeführt wird, verwenden Sie nicht TraceLoggingChannel. Damit ein Ereignis von Ereignisdecodern als TraceLogging-kompatibel erkannt wird, muss der Kanal entweder auf den Standardwert (11) festgelegt sein, oder es muss von der ETW-Laufzeit während EventWrite als TraceLogging-Ereignis markiert worden sein. Diese Ereignismarkierung wird durch Aufrufen von EventSetInformation aktiviert, um den Anbieter als TraceLogging-Anbieter zu konfigurieren. EventSetInformation in Windows 10 oder höher aktiviert die Unterstützung für TraceLogging-Ereignisse unabhängig vom Kanal, aber frühere Versionen von Windows erfordern ein Windows-Update, bevor sie das Markieren von TraceLogging-Ereignissen unterstützen. Für Ereignisse, die auf Systemen ohne aktualisierte EventSetInformation erfasst werden, ist Kanal 11 die einzige Möglichkeit, ein TraceLogging-Ereignis zu erkennen, sodass Ereignisse mit anderen Kanälen möglicherweise nicht ordnungsgemäß decodiert werden.

TraceLogging und Ereignisprotokoll

In den meisten Fällen verwenden Entwickler manifestbasierte ETW für Ereignisse, die vom Ereignisprotokoll aufgezeichnet werden müssen. Das Ereignisprotokoll dient in erster Linie zum Sammeln von Ereignissen mit geringem Volumen, die für den Administrator eines Systems wahrscheinlich nützlich sind. Manifestbasierte ETW eignet sich hierfür gut, da es sorgfältig zusammengestellte Ereignisse unterstützt (alle Ereignisse für die Komponente werden in einer Manifestdatei beschrieben) und weil es lokalisierbare Nachrichtenzeichenfolgen unterstützt, die dem Administrator helfen können, auf das Ereignis zu reagieren.

Obwohl TraceLogging-Ereignisse keine Nachrichtenzeichenfolgen enthalten und in der Regel nicht zentral zusammengestellt werden, kann TraceLogging für einige Ereignisprotokollszenarien dennoch geeignet sein. Während z. B. Ereignisse, die zu den Windows-Protokollen (Anwendung, Sicherheit, Setup und System) gehen, immer lokalisierte Nachrichtenzeichenfolgen aufweisen sollten und für den Systemadministrator immer nützlich sein sollten, können ereignisse, die in den Anwendungs- und Dienstprotokollen aufgezeichnet werden, technischer sein und Diagnoseinformationen aufzeichnen. Beim Schreiben in die Anwendungs- und Dienstprotokolle sollten Sie TraceLogging verwenden, um die Verwaltung der protokollierten Ereignisse zu vereinfachen.

Die Verwendung von TraceLogging-Ereignissen mit Dem Windows-Ereignisprotokoll ähnelt der Verwendung normaler manifestbasierter Ereignisse mit dem Ereignisprotokoll. Sie müssen weiterhin ein Manifest erstellen und registrieren, um den Anbieter und die Kanäle zu definieren, aber Sie müssen nicht die einzelnen Ereignisse im Manifest definieren:

  • Schreiben Sie ein ETW-Manifest , das Ihren Anbieter und die Ereignisprotokollkanäle definiert. Der Anbieter im Manifest sollte den gleichen Anbieternamen und dieselbe Anbieter-GUID (Anbieter-ID) wie in Ihrem TRACELOGGING_DEFINE_PROVIDER-Makro verwenden. Das Manifest muss oder keine Definitionen enthalten <event><template> , da TraceLogging-Ereignisse selbstbeschreibend sind.
  • Verwenden Sie im Buildprozess für Ihre Komponente den Message Compiler (MC.exe) von Windows SDK 10.0.22621 oder höher, um das Manifest zu kompilieren. Dadurch werden die folgenden Dateien generiert:
    • ManifestName.h: C/C++-Header mit Konstantendefinitionen. Dadurch werden das ChannelSymbol und die ChannelSymbol_KEYWORD Konstanten definiert, die Sie in Ihren TraceLogging-Ereignissen verwenden müssen. (Die tatsächlichen Namen der Konstanten sind für jeden Kanal unterschiedlich.)
    • ManifestName.rc: Ressourcencompilerskript (RC.exe), das die BIN-Manifestdaten zu einer Binärdatei (EXE, DLL oder SYS) hinzufügt. Sie müssen dieses Ressourcenskript in die Ressourcen einer der Binärdateien in Ihrer Komponente einschließen.
    • ManifestNameTEMP.BIN, MSG00001.bin: Manifest-BIN-Daten, auf die von verwiesen wird ManifestName.rc.
  • #include die generierte ManifestName.h Datei in den Code, der TraceLogging-Ereignisse generieren muss. Dadurch werden die Konstanten ChannelSymbol und ChannelSymbol_KEYWORD definiert.
    • Wenn Sie das Symbol-Attribut in der <channel> - oder <importChannel> -Definition im Manifest angegeben haben, ist der Name von ChannelSymbol der Wert Ihres Symbol-Attributs . Andernfalls wird ChannelSymbolProviderSymbol_CHANNEL_ChannelName (d. h., es verwendet das Symbol aus Ihrem <provider> Element und den Namen des <channel> Elements oder <importChannel> ).
    • Der Name von ChannelSymbol_KEYWORD ist der Name von ChannelSymbol gefolgt von _KEYWORD.
    • Die ChannelSymbol_KEYWORD Konstante wird nur von MC.exe 10.0.22621 oder höher generiert.
  • Jedes TraceLogging-Ereignis, das zum Ereignisprotokoll wechseln soll, muss verwenden.TraceLoggingChannel(ChannelSymbol), TraceLoggingKeyword(ChannelSymbol_KEYWORD), um den Kanal und die Schlüsselwort (keyword) für das Ereignis festzulegen. Wenn das Symbol meines Kanals beispielsweise lautetMY_CHANNEL, würde ich dem Makro für das TraceLoggingWrite Ereignis als Parameter hinzufügenTraceLoggingChannel(MY_CHANNEL), TraceLoggingKeyword(MY_CHANNEL_KEYWORD).
  • Damit das Ereignisprotokoll Ihren Anbieter erkennt, müssen die Informationen aus Ihrem Manifest in den Ressourcen eines Moduls (DLL-, EXE- oder SYS-Datei) enthalten sein, das auf dem Zielsystem installiert wird.
  • Damit das Ereignisprotokoll Ereignisse von Ihrem Anbieter empfangen kann, müssen Sie Ihr Manifest während der Komponenteninstallation auf dem Zielsystem mit wevtutil im ManifestFile.man /rf:PathToModuleWithResources.dll registrieren. Sie müssen auch die Registrierung Ihres Manifests mit wevtutil um ManifestFile.man während der Komponenteninstallation aufheben.

Wichtig

Wenn Ihr Anbieter beim Ereignisprotokoll registriert ist, muss für alle von Ihrem Anbieter generierten Ereignisse ein Schlüsselwort (keyword) ungleich 0 (null) mit TraceLoggingKeyword angegeben sein, auch wenn das Ereignis nicht für das Ereignisprotokoll vorgesehen ist. Ereignisse mit Schlüsselwort (keyword) 0 können nicht effizient gefiltert werden und werden nur zum Verwerfen an das Ereignisprotokoll übermittelt. Wenn das Ereignisprotokoll auf Ereignisse von Ihrem Anbieter lauscht, erhöht jedes Ereignis mit Schlüsselwort 0 den Ereignisprotokollmehraufwand unnötig.

Beispiel für ein TraceLogging-Ereignis für das Ereignisprotokoll:

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

Bei Bedarf können zusätzliche benutzerdefinierte Schlüsselwörter zu Ereignissen hinzugefügt werden, entweder mithilfe mehrerer TraceLoggingKeyword-Argumente oder durch Angeben mehrerer Schlüsselwörter in einem einzelnen TraceLoggingKeyword-Argument , z. B. TraceLoggingKeyword(MY_CHANNEL_KEYWORD | MY_OTHER_KEYWORD).

Anforderungen

Anforderung Wert
Unterstützte Mindestversion (Client) Windows 10 [nur Desktop-Apps]
Unterstützte Mindestversion (Server) Windows Server 2012 R2
Zielplattform Windows
Kopfzeile traceloggingprovider.h

Weitere Informationen

EVENT_DESCRIPTOR

TraceLoggingWrite

TraceLogging-Wrappermakros