在 Windows 驅動程式中新增 WPP 軟體追蹤

若要在追蹤提供者中使用 WPP 軟體追蹤，例如內核模式驅動程式或使用者模式應用程式，您必須新增程式代碼（或檢測）驅動程式來源檔案，並修改驅動程序專案。本節將說明這些步驟。

備註

在驅動程式中加入 WPP 追蹤最簡單的方法是使用 Visual Studio 中的 KMDF 或 UMDF 驅動範本。如果您使用範本，您需要新增的大部分程式代碼都已經為您完成。在 Visual Studio 中，選取 [ 檔案 > 新 > 專案]，然後選取 Windows 驅動程式（使用者模式或核心模式） WDF 專案。 WPP 巨集在專案中隨附的 Trace.h 頭檔中定義。如果您使用其中一個範本，您可以直接跳到步驟 5。

步驟 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 中（工具 > 建立 GUID）。您也可以使用可從 Visual Studio 命令提示字元視窗取得的 Uuidgen.exe 工具（如需詳細資訊 ，請輸入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_LEVEL_ENABLED 和 WPP_LEVEL_LOGGER 巨集來定義一對巨集：WPP_<條件>_LOGGER 和 WPP_<條件>_ENABLED。

術語	說明
WPP_CONDITIONS_LOGGER	用來尋找與提供者相關聯的追蹤會話，並返回會話的控制代碼。
WPP_條件_ENABLED	用來判斷是否以指定的條件啟用記錄。

針對您定義的 WPP 巨集，CONDITIONS 代表追蹤訊息函式所支援的條件，按照函式中參數列表出現的順序排列，并以底線分隔。例如，默認追蹤訊息函式 DoTraceMessage 僅支援追蹤旗標作為條件，因此巨集名稱中只有一個參數（WPP_LEVEL_ENABLED）。

備註

不幸的是，預設巨集（WPP_LEVEL_ENABLED 和 WPP_LEVEL_LOGGER）名稱似乎標示的是 Trace Level 參數，但實際上它們指的是 Trace Flag。

如果您使用自訂追蹤訊息函式，您可以設定其他限定符，例如追蹤層級。追蹤層級定義於 Evntrace.h 檔案中，而追蹤層級提供將追蹤訊息分類為錯誤、警告和參考訊息的便利方式。

例如，您可以將下列代碼段新增至您新增至項目的頭檔。以下程式碼定義了自訂的 WPP 巨集，這些巨集用於追蹤訊息函式，並支援將 Trace Level 和 Trace Flag 參數作為生成追蹤訊息的條件。如果記錄已為指定的 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 compatibility 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_<condition>_LOGGER 和 WPP_<condition>_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 和 .tmh）

如果您在頭檔（例如 trace.h）中為驅動程式定義控件 GUID 和追蹤旗標，則必須在原始程式檔中包含頭檔，以初始化和卸除 WPP （步驟 4）或呼叫追蹤訊息函式。

此外，您必須為追蹤訊息頭檔 （.tmh）新增 #include 語句。當您建置驅動程式或應用程式時，WPP 預處理器會針對包含追蹤訊息函式的每個來源檔案產生追蹤訊息頭檔（.tmh）。

/* -- 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 例程，或新增至使用者模式驅動程式（UMDF 1.x）或應用程式的 DLLMain 例程。

在驅動程式退出時清理 WPP 資源

將 WPP_CLEANUP 巨集新增至內核模式驅動程式或 UMDF 2.0 驅動程式的驅動程式卸除例程（例如 DriverContextCleanup 或 DriverUnload）。

針對使用者模式驅動程式（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 語句會在追蹤會話中啟用由 WPP_CONTROL_GUIDS 定義的 TRACE_DRIVER 旗標後，寫入包含 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);

使用 TraceEvents 陳述式

如果你在 Visual Studio 中使用 Windows 驅動程式範本， TraceEvents 巨集會在 Trace.h 標頭檔中為你定義。

將 TraceEvents 巨集新增至程式碼，就像除錯列印例程一樣。 TraceEvents 巨集會採用下列參數：追蹤層級（Level）和追蹤旗標（Flags），這些參數定義了寫入追蹤訊息的條件，還有訊息字串和可選的變數清單。
```
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 檔案中，追蹤等級提供了一種方便的方式，將追蹤訊息分類為關鍵訊息、錯誤訊息、警告訊息及資訊訊息。

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-11-20