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

發行項
02/06/2024

本主題描述如何在內核模式驅動程式和元件中使用 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>

注意

開發核心模式驅動程式時，TraceLoggingProvider.h 需要 wdm.h 檔案。

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

新增 TRACELOGGING_DECLARE_PROVIDER 宏以宣告提供者句柄變數。宏具有語法：
```
TRACELOGGING_DECLARE_PROVIDER(hProviderVariableName)
```
下列範例 TraceLogging 語句會宣告名為 g_hProvider 的變數。
```
TRACELOGGING_DECLARE_PROVIDER(g_hProvider);
```
當您稍後在程式代碼中呼叫 TRACELOGGING_DEFINE_PROVIDER 宏時，您使用 TRACELOGGING_DECLARE_PROVIDER 宣告的變數會成為提供者的句柄。

注意

您可能想要將此宏放在頭檔中，以便全域提供 TraceLogging 提供者的句柄。
新增 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宏預期傳遞給它的變數位於非分頁集區中。如果這不是這種情況，呼叫端必須先透過 uniqueVarName) #pragma data_seg (設定數據區段，或透過 g_hMyProvider) 的 #pragma const_seg (const 區段，再呼叫 TRACELOGGING_DEFINE_PROVIDER 宏。

向 TraceLogging 註冊驅動程式

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

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

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

在 DriverUnload 或 cleanup 函式中，取消註冊 TraceLogging 提供者。

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

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

TraceLogging 提供記錄事件的宏。

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

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

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

注意

如果您使用 C++，您可以使用 TraceLoggingValue 包裝函式宏來自動調整類型。如果您要以 C 撰寫驅動程式，則必須使用類型特定的欄位宏 (，例如 TraceLoggingInt32 或 TraceLoggingUnicodeString) 。

下列範例會記錄提供者的事件，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 數據。

共用方式為