共用方式為

TraceLoggingChannel 宏 (traceloggingprovider.h)

  • 發行項

TraceLogging 包裝函式宏 ，可設定事件的通道。

大部分的 TraceLogging 事件不需要變更事件的預設通道，而且不應該使用 TraceLoggingChannel。

語法

void TraceLoggingChannel(
  [in]  eventChannel
);

參數

[in] eventChannel

事件應該記錄到其中的通道。 這是從 0 到 255 的整數值。

如需事件通道的詳細資訊 ，請參閱EVENT_DESCRIPTOR 。

傳回值

無

備註

TraceLoggingChannel(eventChannel) 可作為 TraceLoggingWrite 宏調用的參數。 大部分的 TraceLogging 事件不需要變更事件的預設通道，而且不應該使用 TraceLoggingChannel。

eventChannel 參數必須是編譯時間常數 0 到 255。 TraceLoggingChannel(n)如果未提供arg，則預設通道為11 (WINEVENT_CHANNEL_TRACELOGGING) ，表示這是正常的TraceLogging事件。 如果提供多個 TraceLoggingChannel(n) 自變數，將會使用來自最後 TraceLoggingChannel(n) 一個參數的值。

通道用於 Windows (ETW) 案例的進階事件追蹤。 其中包括寫入系統定義的事件取用者，例如 Windows 事件記錄檔。

警告

如果您的提供者將在 Windows 10 之前的 Windows 上執行，請勿使用 TraceLoggingChannel。 若要讓事件被事件譯碼器辨識為 TraceLogging 相容，它必須將通道設定為預設值 (11) ，或者它必須在 EventWrite 期間由 ETW 運行時間標示為 TraceLogging 事件。 呼叫 EventSetInformation 將提供者設定為 TraceLogging 提供者，以啟用此事件標記。 不論通道為何，Windows 10 或更新版本中的 EventSetInformation 都支援 TraceLogging 事件，但舊版 Windows 需要 Windows 更新，才能支援標記 TraceLogging 事件。 對於在未更新 EventSetInformation 的系統上擷取的事件，通道 11 是辨識 TraceLogging 事件的唯一方法，因此具有其他通道的事件可能無法正確譯碼。

TraceLogging 和事件記錄檔

在大部分情況下，開發人員會針對需要由事件記錄檔記錄的事件使用指令清單型 ETW。 事件記錄檔主要用於收集可能對系統系統管理員有用的低磁碟區事件。 指令清單型 ETW 適用於此情況，因為它支援謹慎策劃的事件， (元件的所有事件都會在一個指令清單檔案) 中描述，而且它支援可本地化的訊息字串，可協助系統管理員知道如何回應事件。

雖然 TraceLogging 事件沒有訊息字串，而且通常不是集中策劃，但 TraceLogging 仍適用於某些事件記錄檔案例。 例如，雖然移至 Windows 記錄 (應用程式、安全性、安裝程式和系統) 的事件應該一律具有本地化的訊息字串，而且應該一律對系統管理員有用，但應用程式與服務記錄檔中記錄的事件可能更具技術性，而且可以記錄診斷資訊。 寫入應用程式與服務記錄檔時，您可能會想要使用 TraceLogging 來簡化記錄事件的管理。

搭配 Windows 事件記錄檔使用 TraceLogging 事件類似於搭配事件記錄檔使用一般指令清單型事件。 您仍然需要建立和註冊指令清單來定義提供者和通道，但不需要在指令清單中定義個別事件：

  • 撰寫 ETW 指令清單 ，以定義您的提供者和事件記錄檔通道。 指令清單中的提供者應該使用相同的提供者名稱和提供者 guid (提供者標識碼) ，如同您在 TRACELOGGING_DEFINE_PROVIDER 宏中使用的一樣。 指令清單不需要包含 <event> 或 <template> 定義，因為 TraceLogging 事件是自我描述的。
  • 在元件的建置程式中，使用來自 Windows SDK 10.0.22621 或更新版本的訊息編譯程式 (MC.exe) 來編譯指令清單。 這會產生下列檔案：
    • ManifestName.h：包含常數定義的 C/C++ 標頭。 這會定義 ChannelSymbol 和 ChannelSymbol_KEYWORD常數 ，您必須在 TraceLogging 事件中使用。 (每個通道的實際常數名稱會有所不同。)
    • ManifestName.rc： 資源編譯程式 (RC.exe) 腳本，可將指令清單 BIN 數據新增至二進位 (EXE、DLL 或 SYS) 檔案。 您必須將此資源文稿包含在元件中其中一個二進位檔的資源中。
    • ManifestNameTEMP.BIN， MSG00001.bin：所參考的 ManifestName.rc指令清單 BIN 數據。
  • #include 產生的 ManifestName.h 檔案到需要產生 TraceLogging 事件的程式代碼中。 這會定義 ChannelSymbol 和 ChannelSymbol_KEYWORD 常數。
    • 如果您在指令清單中的 或 <importChannel> 定義上<channel>指定符號屬性，ChannelSymbol 的名稱將是符號屬性的值。 否則， ChannelSymbol 將會 ProviderSymbol_CHANNEL_ChannelName (，亦即它會使用元素 <provider> 中的符號，以及來自 或 <channel><importChannel> 元素的名稱) 。
    • ChannelSymbol_KEYWORD的名稱是 ChannelSymbol 的名稱，後面接著 _KEYWORD。
    • ChannelSymbol_KEYWORD常數只會由 MC.exe 10.0.22621或更新版本產生。
  • 每個要移至事件記錄檔的 TraceLogging 事件都必須使用TraceLoggingChannel(ChannelSymbol), TraceLoggingKeyword(ChannelSymbol_KEYWORD) 設定事件的通道和關鍵詞。 例如，如果我的通道符號是 MY_CHANNEL，我就會將 做為事件宏的參數新增TraceLoggingChannel(MY_CHANNEL), TraceLoggingKeyword(MY_CHANNEL_KEYWORD)。TraceLoggingWrite
  • 為了讓事件記錄檔辨識您的提供者，指令清單中的資訊 必須包含在模組的資源 中， (DLL、EXE 或 SYS 檔案) 安裝於目標系統上。
  • 若要讓事件記錄檔從您的提供者接收事件，您必須在元件安裝期間使用 wevtutil im ManifestFile.man /rf:PathToModuleWithResources.dll 在目標系統上註冊您的指令清單。 您也必須在元件卸載期間，使用 wevtutil um ManifestFile.man 取消註冊指令清單。

重要

如果您的提供者已向事件記錄檔註冊，則提供者所產生的所有事件 都必須 以 TraceLoggingKeyword 指定非零關鍵詞，即使事件不適用於事件記錄檔也一樣。 關鍵詞 0 的事件無法有效率地篩選，而且只會傳遞至事件記錄檔以捨棄。 如果事件記錄檔正在接聽來自提供者的任何事件，則具有關鍵詞0的任何事件都會不必要地增加事件記錄檔額外負荷。

事件記錄檔的 TraceLogging 事件範例：

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

如有需要，您可以使用多個 TraceLoggingKeyword 自變數，或在單一 TraceLoggingKeyword 自變數中指定多個關鍵詞，例如 ，將其他使用者指定的關鍵詞新增至事件。 TraceLoggingKeyword(MY_CHANNEL_KEYWORD | MY_OTHER_KEYWORD)

規格需求

需求 值
最低支援的用戶端 Windows 10 [僅限傳統型應用程式]
最低支援的伺服器 Windows Server 2012 R2
目標平台 Windows
標頭 traceloggingprovider.h

另請參閱

EVENT_DESCRIPTOR

TraceLoggingWrite

TraceLogging 包裝函式宏