內核模式驅動程式和元件的 TraceLogging

本主題描述如何從內核模式驅動程式和元件內使用 TraceLogging API。

先決條件：

• Windows 10
• Visual Studio 2013 （或更新版本）
• Windows 10 SDK
• 適用於 Windows 10 的 Windows 驅動程式套件 （WDK）

包含 TraceLogging 標頭檔案

若要使用 TraceLogging API，請包含 TraceLogging 頭檔 TraceLoggingProvider.h。 其他 TraceLogging API 頭檔 TraceLoggingActivity.h 僅適用於以 C++ 撰寫的使用者模式驅動程式。

#include <wdm.h>
#include <TraceLoggingProvider.h> 

將您的驅動程式宣告為 TraceLogging 提供者

1. 新增 TRACELOGGING_DECLARE_PROVIDER 巨集以宣告提供者控制代碼變數。 此巨集的語法為：

   TRACELOGGING_DECLARE_PROVIDER(hProviderVariableName)
   

   下列範例 TraceLogging 語句會宣告名為 g_hProvider 的變數。

   TRACELOGGING_DECLARE_PROVIDER(g_hProvider);
   

   使用 TRACELOGGING_DECLARE_PROVIDER 宣告的變數，會成為您稍後在程式代碼中呼叫 TRACELOGGING_DEFINE_PROVIDER 巨集時提供者的句柄。

   備註

   您可能想要將這個巨集放在標頭檔案中，以便使 TraceLogging 提供者的控制代碼可供全域使用。

2. 新增 TRACELOGGING_DEFINE_PROVIDER 巨集，並指定追蹤提供者和追蹤提供者控制代碼的名稱。 句柄是您在步驟 1 中宣告的變數。 巨集的語法為：

   TRACELOGGING_DEFINE_PROVIDER(hProviderVariableName, "ProviderName", providerId [,option])
   

   例如，下列語句會定義名為 MyTraceLoggingProviderKM 的提供者，並將它指派給句柄g_hProvider。 providerId 參數是 ETW 提供者 GUID。

   TRACELOGGING_DEFINE_PROVIDER(g_hProvider, "MyTraceLoggingProviderKM",
       (0xb3864c38, 0x4273, 0x58c5, 0x54, 0x5b, 0x8b, 0x36, 0x08, 0x34, 0x34, 0x71));
   

   TRACELOGGING_DEFINE_PROVIDER 巨集會為提供者分配儲存空間，並定義一個對應變數，這個變數作為提供者的全域性句柄。 提供者名稱必須是字串常值（不是變數），而且不能包含任何 『\0』 字元。 只要原始句柄在範圍內，句柄和其副本就有效。

   當您第一次使用 TRACELOGGING_DEFINE_PROVIDER 巨集建立句柄時，提供者會處於未註冊的狀態。 在此狀態下，提供者會忽略任何追蹤寫入呼叫，直到註冊為止。

   備註

   針對內核模式，請注意，雖然提供者元數據已明確儲存到 TLG_METADATA_SEGMENT （.rdata），但您為句柄建立的變數（例如，g_hProvider），以及提供者的名稱（例如“MyTraceLoggingProviderKM”）並未明確指派區段，而且會使用目前的隱含區段。

TRACELOGGING_DEFINE_PROVIDER巨集預期傳遞給它的變數會位於非分頁集區中。 如果情況並非如此，呼叫端必須先透過 #pragma data_seg 針對 uniqueVarName 設定數據區段，或透過 #pragma const_seg 針對 g_hMyProvider 設定常數區段，再呼叫 TRACELOGGING_DEFINE_PROVIDER 巨集。

使用 TraceLogging 註冊驅動程式

在您的 DriverEntry 函式中，您必須註冊 TraceLogging 提供者。 若要向 TraceLogging 註冊提供者，請將 TraceLoggingRegister 巨集新增至 DriverEntry：

// Register the TraceLogging provider in the DriverEntry method.
TraceLoggingRegister(g_hProvider);

在驅動程式卸除或清除例程中取消註冊提供者

在您的 DriverUnload 或清除函式中，取消註冊 TraceLogging 提供者。

// Stop TraceLogging and unregister the provider
TraceLoggingUnregister(g_hProvider);

在您的程式代碼中記錄事件

TraceLogging 提供用於記錄事件的巨集命令。

基本巨集為 TraceLoggingWrite。 此巨集具有下列語法：

TraceLoggingWrite(g_hProvider, "EventName", args...)

其中g_hProvider是您定義的提供者句柄，而 「EventName」 是用來識別特定事件的字串常值（而非變數）。 如同 printf 或 DbgPrint，TraceLoggingWrite 巨集支援一個可變數目的額外參數（最多 99 個）。 參數 （args） 必須是 TraceLogging 包裝函式巨集，例如 TraceLoggingLevel、 TraceLoggingInt32 或 TraceLoggingString。 TraceLogging 包裝函式巨集定義於 TraceLoggingProvider.h 中。

下列範例會記錄提供者的事件，g_hProvider。 此事件稱為 「MyDriverEntryEvent」。巨集會使用 TraceLoggingPointer 和 TraceLoggingUnicodeString 包裝函式，將指標寫入至追蹤記錄檔的驅動程式對象和登錄路徑。 TraceLoggingUnicodeString 包裝函式會採用選擇性名稱。 在此範例中，“RegPath” 是 RegistryPath 值的名稱。 如果未指定任何名稱，則會使用 值做為名稱。

TraceLoggingWrite(
        g_hProvider,
        "MyDriverEntryEvent",
        TraceLoggingPointer(DriverObject),
        TraceLoggingUnicodeString(RegistryPath, "RegPath")); 
);

如果您要檢測內核模式驅動程式 （在 C 中），您可以連結至 TraceLoggingProvider.h，而且您可以使用 TraceLoggingWrite、TraceLoggingWriteActivity 或 TraceLoggingActivityMarker 巨集。 如需追蹤記錄的範例，請參閱 TraceLogging 範例。

如果您要檢測以 C++ 撰寫的驅動程式或元件，請連結到 TraceLoggingProvider.h 和 TraceLoggingActivity.h。 當您連結至 C++ 標頭時，可以使用 TraceLoggingWriteStart、TraceLoggingWriteStop 和 TraceLoggingWriteTagged 巨集來記錄事件。

如需如何擷取和檢視 TraceLogging 數據的範例，請參閱 擷取和檢視 TraceLogging 數據。