將 WPP 軟體追蹤新增至 Windows 驅動程式
若要在追蹤提供者中使用 WPP 軟體追蹤，例如核心模式驅動程式或使用者模式應用程式，您必須新增程式碼 (或 檢測) 驅動程式原始程式檔，並修改驅動程式專案。 本節將說明這些步驟。
提示 將 WPP 追蹤新增至驅動程式的最簡單方式，就是在 Visual Studio 中使用其中一個 KMDF 或 UMDF 驅動程式範本。 如果您使用範本，您需要新增的大部分程式碼都已經為您完成。 在 Visual Studio 中，選取 [ 檔案 > 新 > 專案]，然後選取 Windows 驅動程式 (使用者模式或核心模式) WDF 專案。 WPP 巨集定義于包含在專案的 Trace.h 標頭檔中。 如果您使用其中一個範本，您可以直接跳至 步驟 5。
- 步驟 1：定義控制項 GUID 和追蹤旗標
- 步驟 2：選擇要使用的追蹤訊息函式，並定義這些函式的 WPP 宏
- 步驟 3：在您的 C 或 C++ 來源檔案中包含相關聯的追蹤標頭檔 (.h 和 .ttl)
- 步驟 4：將宏新增至適當的回呼函式，以初始化和清除 WPP
- 步驟 5：檢測驅動程式程式碼，以在適當的時間點產生追蹤訊息
- 步驟 6：修改 Visual Studio 專案以執行 WPP 預處理器並建置解決方案
- 步驟 7：啟動追蹤會話以擷取並驗證追蹤訊息
步驟 1：定義控制項 GUID 和追蹤旗標
每個追蹤提供者 (例如驅動程式或使用者模式應用程式) 都必須是唯一定義的。 您可以新增定義控制項 GUID、識別碼和追蹤旗標 的WPP_CONTROL_GUIDS 宏來執行此動作。 如此一來，您就可以識別及控制您想要追蹤的時機和專案。 雖然每個驅動程式通常都有個別的控制項 GUID，但驅動程式可以有多個控制項 GUID，或多個驅動程式可以共用一個控制項 GUID。
為了方便起見， WPP_CONTROL_GUIDS 宏通常會定義在一般標頭檔中。 標頭檔必須包含 (#include) 您要檢測追蹤的任何原始程式檔中。
若要將WPP_CONTROL_GUIDS宏新增至驅動程式：
將新的 C++ 標頭檔新增至 Visual Studio 專案，供您用來定義 WPP 追蹤宏。 例如，選取並保留 (或以滑鼠右鍵按一下) 方案總管中的驅動程式，然後選取 [新增 > 專案]。 將檔案儲存 (為 Trace.h，例如) 。
新增 WPP_CONTROL_GUIDS 宏以指定追蹤提供者的易記名稱、定義控制項 GUID，以及定義可用來限定特定追蹤訊息的追蹤旗標。
WPP_CONTROL_GUIDS宏具有下列語法：
WPP_CONTROL_GUIDS的語法
#define WPP_CONTROL_GUIDS \ WPP_DEFINE_CONTROL_GUID(GUIDFriendlyName, (ControlGUID), \ WPP_DEFINE_BIT(NameOfTraceFlag1) \ WPP_DEFINE_BIT(NameOfTraceFlag2) \ ............................. \ ............................. \ WPP_DEFINE_BIT(NameOfTraceFlag31) \ )例如，下列程式碼使用 myDriverTraceGuid 作為 GUIDFriendlyName。 請注意 ，ControlGUID 的格式與 32 位數十六進位 GUID 的標準格式稍有不同。 ControlGUID有五個欄位，但以逗號分隔，並以括弧括住，而不是一般的連字號和大括弧。 例如，您可以指定 ( (84bdb2e9，829e，41b3，b891，02f454bc2bd7) ，而不是 {84bdb2e9-829e-41b3-b891-02f454bc2bd7}。
WPP_CONTROL_GUIDS 語句的範例
#define WPP_CONTROL_GUIDS \ WPP_DEFINE_CONTROL_GUID( \ myDriverTraceGuid, (84bdb2e9,829e,41b3,b891,02f454bc2bd7), \ WPP_DEFINE_BIT(MYDRIVER_ALL_INFO) /* bit 0 = 0x00000001 */ \ WPP_DEFINE_BIT(TRACE_DRIVER) /* bit 1 = 0x00000002 */ \ WPP_DEFINE_BIT(TRACE_DEVICE) /* bit 2 = 0x00000004 */ \ WPP_DEFINE_BIT(TRACE_QUEUE) /* bit 3 = 0x00000008 */ \ )提示 您可以將此程式碼片段複製到標頭檔。 請務必變更控制項 GUID 和易記名稱。 您可以使用GUIDgen.exe來產生控制項 GUID。 Guidgen.exe隨附于 Visual Studio (Tools > Create GUID) 。 您也可以使用 Uuidgen.exe 工具，可從 Visual Studio 命令提示字元視窗 (輸入 uuidgen.exe /？ ，以取得詳細資訊) 。
定義追蹤提供者 的追蹤旗 標。
WPP_CONTROL_GUIDS宏的WPP_DEFINE_BIT元素會定義追蹤提供者的追蹤旗標。 一般而言，旗標代表越來越詳細的報告層級，但您可以使用旗標做為產生追蹤訊息的條件。 在WPP_CONTROL_GUIDS範例中，WPP_DEFINE_BIT定義四個追蹤旗標 (MYDRIVER_ALL_INFO、TRACE_DRIVER、TRACE_DEVICE和TRACE_QUEUE) 。
您最多可以定義 31 個追蹤旗標。 WPP 會依出現的順序，將位值指派給元素，例如，位 0 (0x1) 、位 1 (0x2) 、位 2 (0x4) 、位 3 (0x8) 等等。 當您將追蹤訊息函式新增至原始程式碼時，請使用追蹤旗標， (步驟 5：檢測驅動程式程式碼，以在適當的點產生追蹤訊息) 。
注意 您可以使用追蹤旗標來控制追蹤特定元件 (的時機，例如特定 I/O 要求，或裝置或驅動程式物件的活動) 。 您可以將追蹤旗標新增至追蹤訊息語句 (例如
DoTraceMessage (TRACE_DRIVER, "Hello World!\n")。 當您使用追蹤控制器建立追蹤會話，例如 Tracelog時，您會指定該會話中追蹤提供者使用的 -flag 選項，在此案例中，旗標是位 1 (0x1) ，對應至TRACE_DRIVER旗標。 當您啟動追蹤會話時，指定追蹤旗標的所有追蹤訊息都會寫入記錄檔。
步驟 2：選擇要使用的追蹤訊息函式，並定義這些函式的 WPP 宏
如同偵錯列印函式，追蹤訊息函式是函式 (或宏，) 您新增至程式碼以撰寫追蹤訊息。
選擇追蹤訊息函式
預設追蹤訊息函式是 DoTraceMessage 宏。 如果您使用預設函式，您可以控制何時使用提供者的 追蹤旗標 值來產生訊息。 追蹤旗標值是您在步驟 1 中建立控制項 GUID 時所定義的旗標。 如果您使用 DoTraceMessage，則預設 WPP 宏已為您定義 (WPP_LEVEL_ENABLED和WPP_LEVEL_LOGGER) ，因此您可以略過此步驟的其餘部分，並移至 步驟 5。
如果您使用其中一個 KMDF 或 UMDF 範本， TraceEvents 函式和必要的 WPP 宏已定義來啟用該函式，因此您可以直接跳至 步驟 5。
如果您要建立自己的追蹤訊息函式，或轉換現有的偵錯列印函式，請繼續進行此步驟的其餘部分。
建立或自訂追蹤訊息函式
如果您使用自訂追蹤訊息函式，或想要轉換偵錯列印函式 (例如 KdPrint) 來產生追蹤訊息，您必須定義 WPP 宏，以識別並啟用追蹤提供者中的追蹤訊息函式。 將這些宏放在您新增至專案的 Trace.h 標頭檔中。
定義 WPP 宏以啟用追蹤函式。
您使用的每個追蹤訊息函式都必須有對應的一對宏。 這些宏會識別追蹤提供者，並指定產生訊息的條件。 您通常會定義一對宏、WPP_< 條件 >_LOGGER和WPP_< 條件 >_ENABLED就預設WPP_LEVEL_ENABLED和WPP_LEVEL_LOGGER宏而言。
您使用的每個追蹤訊息函式都必須有對應的一對宏。 這些宏會識別追蹤提供者，並指定產生訊息的條件。 您通常會定義一對宏、WPP_< 條件 >_LOGGER和WPP_< 條件 >_ENABLED就預設WPP_LEVEL_ENABLED和WPP_LEVEL_LOGGER宏而言。
| 詞彙 | 描述 |
|---|---|
WPP_CONDITIONS_LOGGER |
用來尋找與提供者相關聯的追蹤會話，並將控制碼傳回給會話。 |
WPP_CONDITIONS_ENABLED |
用來判斷是否使用指定的條件啟用記錄。 |
針對您定義的 WPP 宏， CONDITIONS 代表追蹤訊息函式所支援的條件，依它們出現在函式的參數清單中的順序，並以底線分隔。 例如，預設追蹤訊息函式 DoTraceMessage僅支援 Trace Flag 作為條件，因此宏名稱中只有一個參數 (WPP_LEVEL_ENABLED) 。
注意 不幸的是，預設宏的名稱 (WPP_LEVEL_ENABLED和WPP_LEVEL_LOGGER) 似乎表示 追蹤層級 參數，但實際上會參考追蹤旗標。
如果您使用自訂追蹤訊息函式，您可以設定其他限定詞，例如 追蹤層級。 追蹤層級是在 Evntrace.h 檔案中定義，而追蹤層級提供將追蹤訊息分類為錯誤、警告和參考訊息的便利方式。
例如，您可以將下列程式碼片段新增至您新增至專案的標頭檔。 下列程式碼會定義追蹤訊息函式的自訂 WPP 宏，該函式同時支援 追蹤層級 和追蹤旗標參數作為產生追蹤訊息的條件。 如果針對指定的 FLAGS 值啟用記錄，且啟用的 LEVEL 值大於或等於追蹤訊息函式呼叫中使用的 level 引數， 則WPP_LEVEL_FLAGS_ENABLED 宏會傳回 TRUE。
#define WPP_LEVEL_FLAGS_LOGGER(lvl,flags) \
WPP_LEVEL_LOGGER(flags)
#define WPP_LEVEL_FLAGS_ENABLED(lvl, flags) \
(WPP_LEVEL_ENABLED(flags) && WPP_CONTROL(WPP_BIT_ ## flags).Level >= lvl)
接下來，您必須在 WPP 組態區塊中指定自訂追蹤函式， (begin_wpp組態 和 end_wpp) 例如，如果您在 Visual Studio 中使用 UMDF 或 KMDF 驅動程式專案的範本，此範本會定義名為 TraceEvents之自訂追蹤訊息函式的 WPP 宏。 TraceEvents宏函式會使用追蹤層級和追蹤旗標作為產生訊息的條件。 如果您已在 Trace.h 標頭檔中定義 WPP_LEVEL_FLAGS_ENABLED 宏，您可以新增下列巨集定義。
//
// This comment block is scanned by the trace preprocessor to define the
// TraceEvents function.
//
// begin_wpp config
// FUNC TraceEvents(LEVEL, FLAGS, MSG, ...);
// end_wpp
//
您也可以在 WPP 組態區塊中新增類似的 FUNC 宣告，將現有的偵錯列印語句轉換為追蹤訊息語句。 例如，下列範例會新增程式碼來轉換現有的 KdPrint 語句。 FUNC宣告也會全域定義KdPrint，以使用指定的追蹤層級和旗標 {LEVEL=TRACE_LEVEL_INFORMATION，FLAGS=TRACE_DRIVER}。 偵錯列印語句會傳送至追蹤記錄檔，而不是將輸出傳送至偵錯工具。
//
// This comment block is scanned by the trace preprocessor to define the
// TraceEvents function and conversion for KdPrint. Note the double parentheses for the KdPrint message, for compatiblility with the KdPrint function.
//
// begin_wpp config
// FUNC TraceEvents(LEVEL, FLAGS, MSG, ...);
// FUNC KdPrint{LEVEL=TRACE_LEVEL_INFORMATION, FLAGS=TRACE_DRIVER}((MSG, ...));
// end_wpp
//
注意 如果您想要將 KdPrintEx 轉換成追蹤訊息函式，您需要採取一些額外的步驟。 相較于 KdPrint， KdPrintEx 函式會採用兩個額外的引數。 若要轉換KdPrintEx函式，您必須定義ComponentID的WPP_DEFINE_BIT，並定義自訂<>WPP_條件_LOGGER和WPP_<>條件_ENABLED宏。 KdPrintEx的第二個參數指定 的層級與追蹤層級值類似，因此您不一定需要重新定義它們。
#define WPP_CONTROL_GUIDS \
WPP_DEFINE_CONTROL_GUID(\
myDriverTraceGuid, (11C3AAE4, 0D88, 41b3, 43BD, AC38BF747E19), \ /* change GUID for your provider */
WPP_DEFINE_BIT(MYDRIVER_ALL_INFO) /* bit 0 = 0x00000001 */ \
WPP_DEFINE_BIT(TRACE_DRIVER) /* bit 1 = 0x00000002 */ \
WPP_DEFINE_BIT(TRACE_DEVICE) /* bit 2 = 0x00000004 */ \
WPP_DEFINE_BIT(TRACE_QUEUE) /* bit 3 = 0x00000008 */ \
WPP_DEFINE_BIT(DPFLTR_IHVDRIVER_ID) /* bit 4 = 0x00000010 */\ /* Added for the ComponentID param of KdPrintEx */
)
#define WPP_Flags_LEVEL_LOGGER(Flags, level) \
WPP_LEVEL_LOGGER(Flags)
#define WPP_Flags_LEVEL_ENABLED(Flags, level) \
(WPP_LEVEL_ENABLED(Flags) && \
WPP_CONTROL(WPP_BIT_ ## Flags).Level >= level)
//
// This comment block is scanned by the trace preprocessor to convert the KdPrintEx function.
// Note the double parentheses for the KdPrint message, for compatiblility with the KdPrintEx function.
//
// begin_wpp config
// FUNC KdPrintEx((Flags, LEVEL, MSG, ...));
// end_wpp
//
步驟 3：在您的 C 或 C++ 來源檔案中包含相關聯的追蹤標頭檔 (.h 和 .ttl)
如果您在標頭檔 (中定義驅動程式的控制項 GUID 和追蹤旗標，例如 trace.h) ，則必須在原始程式檔中包含標頭檔，其中您將初始化和卸載 WPP (步驟 4) 或呼叫追蹤訊息函式。
此外，您必須為追蹤訊息標頭檔 (.t) 新增#include語句。 當您建置驅動程式或應用程式時，WPP 預處理器會針對包含追蹤訊息函式的每個來源檔案產生追蹤訊息標頭檔 (.tー) 。
/* -- driver.c - include the *.tmh file that is generated by WPP --*/
#include "trace.h" /* file that defines WPP_CONFIG_GUIDS and trace flags */
#include "driver.tmh" /* this file is auto-generated */
步驟 4：將宏新增至適當的回呼函式，以初始化和清除 WPP
在驅動程式專案上初始化 WPP
- 將 WPP_INIT_TRACING 宏新增至核心模式驅動程式或 UMDF 2.0 驅動程式的 DriverEntry 常式，或新增至使用者模式驅動程式的 DLLMain 常式， (UMDF 1.x) 或應用程式。
清除驅動程式結束時的 WPP 資源
將 WPP_CLEANUP 宏新增至驅動程式卸載常式 (例如 DriverCoNtextCleanup 或 DriverUnload) 核心模式驅動程式或 UMDF 2.0 驅動程式。
針對使用者模式驅動程式 (UMDF 1.x) 或應用程式，請將 WPP_CLEANUP 宏新增至 DLLMain 常式。
如果DriverEntry失敗，您也應該將WPP_CLEANUP宏新增至DriverEntry常式。 例如，如果 DriverEntry 失敗，將不會呼叫驅動程式卸載常式。 請參閱下列範例中的 WdfDriverCreate 呼叫。
在DriverEntry中使用 WPP_INIT_TRACING 和 WPP_CLEANUP 的核心模式驅動程式範例
NTSTATUS
DriverEntry(
_In_ PDRIVER_OBJECT DriverObject,
_In_ PUNICODE_STRING RegistryPath
)
{
// ...
//
// Initialize WPP Tracing in DriverEntry
//
WPP_INIT_TRACING( DriverObject, RegistryPath );
// ...
//
// Create a framework driver object to represent our driver.
//
status = WdfDriverCreate(
DriverObject,
RegistryPath,
&attributes, // Driver Object Attributes
&config, // Driver Config Info
WDF_NO_HANDLE // hDriver
);
if (!NT_SUCCESS(status)) {
TraceEvents(TRACE_LEVEL_ERROR, DBG_INIT,
"WdfDriverCreate failed with status 0x%x\n", status);
//
// Cleanup tracing here because DriverContextCleanup will not be called
// as we have failed to create WDFDRIVER object itself.
// Please note that if you return failure from DriverEntry after the
// WDFDRIVER object is created successfully, you don't have to
// call WPP cleanup because in those cases DriverContextCleanup
// will be executed when the framework deletes the DriverObject.
//
WPP_CLEANUP(DriverObject);
}
return status;
}
在 DriverCoNtextCleanup 中使用 WPP_CLEANUP 的核心模式驅動程式範例
VOID
DriverContextCleanup(
PDRIVER_OBJECT DriverObject
)
{
// ...
// Clean up WPP resources on unload
//
WPP_CLEANUP(DriverObject);
// ...
}
在 DriverEntry 中使用 WPP_INIT_TRACING 的 UMDF 2.0 驅動程式範例
/
// Driver specific #defines in trace header file (trace.h)
//
#define MYDRIVER_TRACING_ID L"Microsoft\\UMDF2.0\\UMDF2_0Driver1 V1.0"
// Initialize WPP Tracing in the DriverEntry routine
//
WPP_INIT_TRACING( MYDRIVER_TRACING_ID );
UMDF 1.0 驅動程式在 DLLMain 中使用WPP_INIT_TRACING和WPP_CLEANUP宏的範例
/
// Driver specific #defines in trace header file (for example, trace.h)
//
#define MYDRIVER_TRACING_ID L"Microsoft\\UMDF1.X\\UMDF1_XDriver1"
//
// DLL Entry Point - UMDF 1.0 example in the source file where you implement the DLL exports.
//
extern "C"
BOOL
WINAPI
DllMain(
HINSTANCE hInstance,
DWORD dwReason,
LPVOID lpReserved
)
{
if (dwReason == DLL_PROCESS_ATTACH) {
WPP_INIT_TRACING(MYDRIVER_TRACING_ID); // Initialize WPP tracing
g_hInstance = hInstance;
DisableThreadLibraryCalls(hInstance);
} else if (dwReason == DLL_PROCESS_DETACH) {
WPP_CLEANUP(); // Deactivate and cleanup WPP tracing
}
return _AtlModule.DllMain(dwReason, lpReserved);
}
步驟 5：檢測驅動程式程式碼，以在適當的時間點產生追蹤訊息
您可以使用您選擇的任何追蹤訊息函式，前提是追蹤訊息函式、追蹤旗標和層級已適當定義。 預設追蹤訊息函式是 DoTraceMessage 宏。 您可以將此宏新增至程式碼，以將訊息寫入記錄檔。 下表列出一些預先定義的追蹤訊息函式，以及可用來建立追蹤訊息的偵錯列印函式。
| 範例追蹤訊息函式 | 使用時機 |
|---|---|
| DoTraceMessage | 這是預設追蹤訊息函式。 使用 DoTraceMessage 的優點是已為您定義函式。 您可以使用您在WPP_CONFIG_GUIDS宏中指定的追蹤旗標。 使用 DoTraceMessage的缺點是函式只會採用一個條件參數，也就是追蹤旗標。 如果您想要使用追蹤層級，只記錄錯誤或警告訊息，您可以使用 DoDebugTrace 宏，或使用 TraceEvents，這同時使用追蹤旗標和追蹤層級。 |
| TraceEvents | 如果您在 Visual Studio 中使用 WDF 範本建立驅動程式，這是預設追蹤訊息函式。 使用 TraceEvents 的優點是追蹤訊息函式、追蹤旗標和 追蹤層級 已為您定義。 此外，範本也包含檢測，會在函式進入和結束時將訊息寫入記錄檔。 |
| KdPrint、 KdPrintEx、 DbgPrint、 DbgPrintEx | 使用偵錯列印函式的優點是您不需要修改現有的偵錯列印語句。 您可以輕鬆地從偵錯工具中檢視訊息切換至在檔案中錄製追蹤訊息。 如果您自訂追蹤訊息函式以包含其中一個偵錯列印函式，則不需要再執行任何工作。 當您使用 Logman 或 Tracelog或其他追蹤控制器建立追蹤會話時，只要指定提供者的旗標和層級即可。 符合您指定條件的任何偵錯列印語句都會列印至記錄。 |
使用 DoTraceMessage 語句
將 DoTraceMessage 宏新增至程式碼，就像偵錯列印常式一樣。 DoTraceMessage宏會採用 3 個參數：旗標層級 (TraceFlagName) ，這會定義寫入追蹤訊息時的條件、Message字串和選擇性變數清單。
DoTraceMessage(TraceFlagName, Message, [VariableList... ]例如，下列 DoTraceMessage 語句會在追蹤會話啟用TRACE_DRIVER WPP_CONTROL_GUIDS旗標時，寫入包含 DoTraceMessage 語句的函式名稱。
DoTraceMessage( TRACE_DRIVER, "\nEntering %!FUNC!" );此範例會針對目前執行的函式使用預先定義的字串， (%FUNC！) 。 如需 WPP 定義格式規格字串的詳細資訊，請參閱 什麼是 WPP 擴充格式規格字串？
若要產生追蹤訊息，請使用 Logman 或 Tracelog為您的追蹤提供者建立追蹤會話，並指定追蹤旗標，以設定TRACE_DRIVER旗標 (位 1，0x2) 。
//
// DoTraceMessage examples
//
...
// writes the name of the function that contains the trace statement when the flag, TRACE_DRIVER (bit 1, 0x2),
// as defined in WPP_CONTROL_GUIDS, is enabled for the trace session.
DoTraceMessage( TRACE_DRIVER, "\nEntering %!FUNC!" );
...
// writes the name of the function, the line number, and the error code
DoTraceMessage(
TRACE_DRIVER,
"[%s] Failed at %d (error code= %d)\n",
__FUNCTION__,
__LINE__,
dwLastError);
如果您在 Visual Studio 中使用 Windows 驅動程式範本， TraceEvents 宏會在 Trace.h 標頭檔中為您定義。
使用 TraceEvents 語句
將 TraceEvents 宏新增至程式碼，就像偵錯列印常式一樣。 TraceEvents宏採用下列參數：追蹤層級 (層級) 和追蹤旗標 (旗標) ，這會定義寫入追蹤訊息時的條件、訊息字串和選擇性變數清單。
TraceEvents(Level, Flags, Message, [VariableList... ]例如，當符合追蹤層級和追蹤旗標參數中指定的條件時，下列TraceEvents語句會寫入包含TraceEvents語句的函式名稱。 追蹤層級是整數值;追蹤會話所指定追蹤層級或以下的任何專案都會追蹤。 TRACE_LEVEL_INFORMATION定義于 Evntrace.h 中，且值為 4。 TRACE_DRIVER旗標 (位 1，0x2) 定義于 WPP_CONTROL_GUIDS。 如果針對追蹤會話設定此TRACE_DRIVER位，且追蹤層級為 4 或更新版本， TraceEvents 會寫入追蹤訊息。
TraceEvents(TRACE_LEVEL_INFORMATION, TRACE_DRIVER, "%!FUNC! Entry");此範例會針對目前執行的函式使用預先定義的字串， (%FUNC！) 。 如需 WPP 定義格式規格字串的詳細資訊，請參閱 什麼是 WPP 擴充格式規格字串？
若要產生追蹤訊息，請使用 Logman 或 Tracelog為您的追蹤提供者建立追蹤會話。 指定追蹤層級以TRACE_LEVEL_INFORMATION (4) 或更新版本，並指定追蹤層級來設定TRACE_DRIVER位 (位 1，0x2) 。
//
// TraceEvents examples
//
TraceEvents(TRACE_LEVEL_INFORMATION, TRACE_DRIVER, "%!FUNC! Entry");
//
TraceEvents(TRACE_LEVEL_INFORMATION, DBG_INIT,
"OSRUSBFX2 Driver Sample - Driver Framework Edition.\n");
TraceEvents(TRACE_LEVEL_INFORMATION, DBG_INIT,
"Built %s %s\n", __DATE__, __TIME__);
步驟 6：修改 Visual Studio 專案以執行 WPP 預處理器並建置解決方案
WDK 提供 WPP 預處理器的支援，讓您可以使用 Visual Studio 和 MSBuild 環境來執行預處理器。
執行 WPP 預處理器
- 選取並按住 (或以滑鼠右鍵按一下) [方案總管] 中的驅動程式專案，然後選取 [ 屬性]。
- 在專案屬性頁面中，選取 [ 組態屬性 ]，然後選取 [WPP 追蹤]。
- 在 [一般] 下，將 [ 執行 WPP] 選項設定為 [是]。
- 在 [命令列] 下，新增任何其他選項以自訂追蹤行為。 如需您可以新增之專案的資訊，請參閱 WPP 預處理器。
- 為您的目標群組態和平臺建置專案或解決方案。 請參閱 使用 WDK 建置驅動程式。
如需建置程式的相關資訊，請參閱 TraceWPP 工作 和 WDK 和 Visual Studio 建置環境。
您也可以使用 TraceWPP 工具 (TraceWPP.exe) ，與建置環境分開執行預處理器。 此工具位於 WDK 的 bin/x86 和 bin/x64 子目錄中。
步驟 7：啟動追蹤會話以擷取並驗證追蹤訊息
若要確認您已正確設定 WPP 追蹤，您應該在測試電腦上安裝驅動程式或應用程式，然後建立追蹤會話來擷取追蹤訊息。 您可以使用任何追蹤控制器，例如 Logman、 Tracelog或 TraceView，為您的追蹤提供者建立追蹤會話。 您可以有寫入記錄檔或傳送至核心偵錯工具的訊息。 根據您使用的追蹤訊息函式，您必須確定指定將產生訊息的追蹤旗標和追蹤層級。
例如，如果您使用 Evntrace.h 中定義的追蹤層級，而且您想要擷取TRACE_LEVEL_INFORMATION (4) 或更新版本，則必須將層級設定為 4。 當您將追蹤會話的層級設定為 4 時，也會擷取所有參考 (4) 、警告 (3) 、錯誤 (2) ，以及擷取重大 (1) 訊息，假設也滿足任何其他條件，例如追蹤旗標。
若要確認所有訊息都已產生，您可能只將追蹤層級和追蹤旗標設定為最大值，以便產生所有訊息。 追蹤旗標會使用位遮罩 (ULONG) ，因此您可以設定所有位 (，例如0xFFFFFFFF) 。 追蹤層級是以位元組值表示。 例如，如果您使用 Logman，您可以指定0xFF涵蓋所有層級。
(範例) 使用 Logman 啟動追蹤會話
logman create trace "myWPP_session" -p {11C3AAE4-0D88-41b3-43BD-AC38BF747E19} 0xffffffff 0xff -o c:\DriverTest\TraceFile.etl
logman start "myWPP_session"
logman stop "myWPP_session"
(範例) 使用 TraceLog 啟動追蹤會話
tracelog -start MyTrace -guid MyProvider.guid -f d:\traces\testtrace.etl -flag 2 -level 0xFFFF
Tracelog命令包含-f參數，可指定事件追蹤記錄檔的名稱和位置。 其中包含指定旗標集的 -flag 參數，以及指定層級設定的 -level 參數。 您可以省略這些參數，但除非您設定旗標或層級，否則某些追蹤提供者不會產生任何追蹤訊息。 追蹤層級是在 Evntrace.h 檔案中定義，而追蹤層級提供將追蹤訊息分類為嚴重、錯誤、警告和參考訊息的便利方式。
意見反應
即將登場：在 2024 年，我們將逐步淘汰 GitHub 問題作為內容的意見反應機制，並將它取代為新的意見反應系統。 如需詳細資訊，請參閱：https://aka.ms/ContentUserFeedback。
提交並檢視相關的意見反應