WPP 預處理器

  • 發行項

本節描述 Windows 軟體追蹤預處理器，通常稱為 WPP 預處理器。

叫用 WPP 預處理器

您可以使用 Visual Studio 和 MSBuild 環境叫用 WPP 預處理器。

叫用 WPP 預處理器

  1. 以滑鼠右鍵按一下 [方案總管] 中的驅動程式專案，然後按一下 [ 屬性]。

  2. 在專案屬性頁面中，按一下 [ 組態屬性 ]，然後按一下 [WPP 追蹤]

  3. 在 [一般] 下，將 [ 執行 WPP ] 選項設定為 [是]。

  4. 在 [命令列] 下，您可以新增下列選項來自訂追蹤行為。

    例如，在 WPP 追蹤下，您可以指定單一 掃描組態資料檔案 。

    如果您需要提供多個組態檔，例如若要指定自訂資料類型，請使用-scan選項在命令列中參考您的檔案，例如：

    -scan:"$(KMDF_INC_PATH)\$(KMDF_VER_PATH)\WdfTraceEnums.h"

如需建置程式的詳細資訊，請參閱 TraceWPP 工作 和 WDK 和 Visual Studio 建置環境。

您也可以使用 TraceWPP 工具 (TraceWPP.exe) ，與建置環境分開執行預處理器。 此工具位於 WDK 的 bin/x86 子目錄中。

WPP 追蹤一般選項

下表描述 WPP 預處理器的選項。 您可以使用專案的 WPP 追蹤屬性頁，或在 TraceWPP 工具的參數中，在 Visual Studio 中設定這些選項。

WPP 追蹤選項 描述

執行 WPP

如果為 true，則叫用 WPP。

啟用最少重建

如果為 true，則會執行追蹤的累加建置;如果為 false，則會執行重建。

函式和宏選項

WPP 追蹤選項 TraceWPP 命令選項 描述

前置處理器定義

-D宏

將 #define宏 新增至所產生檔案的開頭，其中 Macro 是宏的名稱。

此選項的效果與 /D (定義宏) 編譯器選項相同。 它包含在內，以確保定義在T 檔案開頭有效。

-D宏=展開

將#define宏展開新增至所產生檔案的開頭，其中Macro是宏的名稱，而 Expansion是展開的值。

此選項的效果與 /D (定義宏) 編譯器選項相同。 它包含在內，以確保定義在T 檔案開頭有效。

追蹤Kernel-Mode元件

-公里

定義追蹤核心模式元件的WPP_KERNEL_MODE宏。 根據預設，只會追蹤使用者模式元件。

啟用 Dll 宏

-Dll

定義WPP_DLL宏，每當呼叫WPP_INIT_TRACING時，就會初始化 WPP 資料結構。 否則，結構只會初始化一次。

指定控制項 GUID

-ctl：GUID

 使用指定的控制項 GUID和WPP_DEFINE_BIT名為 Error、Unusual 和 Noise 的專案，定義WPP_CONTROL_GUIDS宏。

這是將宏新增至原始程式檔的替代方案。

GUID 代表控制項 GUID。

搜尋和格式化選項

WPP 追蹤選項 TraceWPP 命令選項 描述

忽略驚嘆號

-noshrieks

指示 WPP 忽略驚嘆號，也稱為「shrieks」。

用於複雜的格式設定，例如 %！timestamp！%。 根據預設，需要驚嘆號，WPP 會嘗試解譯它們。

格式字串編號的數值基底

-argbase：Number

建立格式字串編號的數值基底，例如 「%1！d！， %2！s！」。 預設值是 1。

產生追蹤訊息的函式

-func：FunctionDescription

指定 DoTraceMessage 宏的替代方案。 然後，這些函式可用來產生追蹤訊息。

例如，您可以定義函式，指定追蹤訊息的旗標和層級，例如：

-func (DoMyTraceMessage(LEVEL,FLAGS,MSG,...)

您可以使用 -func 選項的多個實例。

此選項是指定本機組態檔中函式描述的替代方案。

指定要搜尋的字串

-lookfor：String

指示 WPP 搜尋來源檔案中的指定字串以起始追蹤。 根據預設，WPP 會搜尋字串 「WPP_INIT_TRACING」。

這是撰寫自己的範本的使用者進階選項。

例如，在 default.tpl 中：

IF FOUND WPP_INIT_TRACING
 INCLUDE um-init.tpl
ENDIF

指定模組名稱

-p：String

指定來自這個追蹤提供者之訊息之訊息 GUID的替代易記名稱。 根據預設，訊息 GUID 的易記名稱是建立追蹤提供者的目錄名稱。

根據預設，訊息 GUID 的易記名稱會出現在變數%1所代表的追蹤訊息前置詞中。 您可以使用此參數將字串新增至前置詞，以協助使用者識別追蹤提供者，例如追蹤提供者的易記名稱、包含追蹤提供者的模組名稱，或建立數個追蹤提供者所實作的專案名稱。 這項資訊可協助使用者關聯位於不同檔案或不同路徑中的相關追蹤提供者。

-p參數需要 Windows Driver Kit (WDK) for Windows Vista 和更新版本的 WDK 中包含的 WPP 版本。 -p參數適用于 Windows 2000 和更新版本的 Windows。

範例：

-p:TraceDrv
-p:AudioModule

檔案選項

WPP 追蹤選項 TraceWPP 命令選項 描述

其他 Include 目錄

-IPath1[;Path2]

指定一或多個要加入 Include 路徑中的目錄；如有多個目錄，請使用分號加以分隔。 與 -cfgdir相同。

組態目錄

-cfgdir：Path1[;Path2]

指定組態和範本檔案的位置。

Path1 和 Path2 代表目錄的完整路徑。 您可以指定多個路徑。 預設值為本機目錄。

副檔名

-內線：。ext1[.ext2]

指定 WPP 辨識為來源檔案的檔案類型。 WPP 會忽略副檔名不同的檔案。

根據預設，WPP 只會辨識 .c、.c++、.cpp 和 .cxx 檔案。

此選項可讓您使用 WPP 的預設設定，而不需要刪除或重新命名 WPP 不使用的資源檔，例如 .rc 和 .mc 檔案。

例如，若要將追蹤新增至 C++ 檔案和標頭 (.h) 檔案，請使用下列命令：

-ext：.cpp。CPP.h.H

此外，若要為 C++ 和標頭檔提供不同的名稱，請使用 -preserveext 選項。

保留副檔名

-preserveext：.ext1[.ext2]

建立T 檔案時，保留指定的副檔名。

根據預設，所有檔案類型的T 檔案都會命名為 filename.t。 當您有多個具有相同名稱的來源檔案時，這會導致檔案名衝突。

例如，根據預設，C 檔案 (.c) 和頭 (.h) 檔案的 TCS 檔案會命名為 < filename.t >) 。 藉由使用 -preserveext：.c .h，TCS 檔案會命名為 < filename.c.ths > 和 < filename.h.ths > 。

輸出目錄

 -odir：path

指定 WPP 所建立輸出檔案的目錄。

Path 是目錄的完整路徑。 預設值為本機目錄。

指定範本檔案

-gen{ File.tpl } . ext

對於 WPP 以大括弧 {} 之間指定名稱處理的每個原始程式檔，建立另一個副檔名為指定的檔案。

File.tpl 代表來源檔案。 *.ext 代表所建立的檔案類型及其副檔名。

您可以指定多個 -gen 選項。

例如， -gen{um-default.tpl} .tvp 表示針對 WPP 處理的每個 um-default.tpl 檔案，會產生 um-default.t 檔案。

掃描設定資料

-scan：File

在不是組態檔的檔案中，以及defaultwpp.ini中搜尋組態資料，例如自訂資料類型。

將 begin_wpp組態 和 end_wpp 字串放在組態資料周圍，以識別它。 針對組態資料使用相同的格式，如同defaultwpp.ini。

如果您將組態資料新增至自訂群組態檔，請使用 -ini 參數。

替代組態檔

-defwpp：path

指定替代組態檔。 Wpp 會使用此檔案，而不是defaultwpp.ini檔案。

其他組態檔

-ini：Path

指定其他組態檔。 WPP 除了預設檔案之外，還會使用指定的檔案，defaultwpp.ini。

當您已建立新的組態檔來儲存組態資料以進行追蹤時，請使用此參數。 如果您已將組態資料新增至其他類型的檔案，例如來源或標頭檔，請使用 -scan 參數。

WPP 建置程式

如果已啟用驅動程式或使用者模式應用程式的 WPP，建置驅動程式或應用程式會在編譯驅動程式或應用程式檔之前叫用 WPP 預處理器。

WPP 建置程式會完成下列步驟：

  1. WPP 預處理器會處理每個來源檔案中的 WPP 宏，並為每個來源檔案建立 追蹤訊息標頭檔 。 原始程式碼不會直接修改。

  2. 在 WPP 預處理器建立追蹤訊息標頭檔之後，C 預處理器會以正常方式處理追蹤訊息標頭檔中的內建 WPP 宏。