WPP 預處理器
本節描述 Windows 軟體追蹤預處理器,通常稱為 WPP 預處理器。
叫用 WPP 預處理器
您可以使用 Visual Studio 和 MSBuild 環境叫用 WPP 預處理器。
叫用 WPP 預處理器
以滑鼠右鍵按兩下 [方案總管] 中的驅動程式專案,然後按下 [ 屬性]。
在專案屬性頁面中,按兩下 [組態屬性 ],然後按兩下 [WPP 追蹤]
在 [一般] 下,將 [執行 WPP] 選項設定為 [是]。
在 [命令行] 底下,您可以新增下列選項來自定義追蹤行為。
例如,在 WPP 追蹤下,您可以指定單一掃描組態資料檔。
如果您需要提供多個組態檔,例如,若要指定自定義數據類型,請使用 -scan 選項在命令行中參考您的檔案,例如:
-scan:"$(KMDF_INC_PATH)\$(KMDF_VER_PATH)\WdfTraceEnums.h"
如需建置程式的詳細資訊,請參閱 TraceWPP 工作 和 WDK 和 Visual Studio 建置環境。
您也可以使用 TraceWPP 工具 (TraceWPP.exe) 來執行與建置環境分開的預處理器。 此工具位於 WDK 的 bin/x86 子目錄中。
WPP 追蹤一般選項
下表描述 WPP 預處理器的選項。 您可以使用專案的 WPP 追蹤屬性頁,或在 Visual Studio 中設定這些選項,或做為 TraceWPP 工具的參數。
WPP 追蹤選項 | 描述 |
---|---|
執行 WPP |
如果為 true,則會叫用 WPP。 |
啟用最小重建 |
如果為 true,則會執行追蹤的累加建置;如果為 false,則會執行重建。 |
函式和宏選項
WPP 追蹤選項 | TraceWPP 命令選項 | 描述 |
---|---|---|
前置處理器定義 |
-D宏 |
將 #define 宏 新增至產生的檔案開頭,其中 Macro 是宏的名稱。 此選項的效果與 /D (定義宏) 編譯程式選項相同。 其包含在內,以確保定義在TMH檔案開頭有效。 |
-D宏=展開 |
將 #define 宏展開 新增至產生的檔案開頭,其中 Macro 是宏的名稱,而 Expansion 則是展開的值。 此選項的效果與 /D (定義宏) 編譯程式選項相同。 其包含在內,以確保定義在TMH檔案開頭有效。 |
|
追蹤內核模式元件 |
-公里 |
定義追蹤內核模式元件的WPP_KERNEL_MODE宏。 根據預設,只會追蹤使用者模式元件。 |
啟用 Dll 宏 |
-dll |
定義WPP_DLL宏,每當呼叫WPP_INIT_TRACING時,就會初始化 WPP 數據結構。 否則,結構只會初始化一次。 |
指定控制項 GUID |
-ctl: GUID |
使用指定的控件 GUID 和WPP_DEFINE_BIT名為 Error、異常和雜訊的專案,定義WPP_CONTROL_GUIDS宏。
這是將宏新增至原始程序檔的替代方法。 GUID 代表控件 GUID。 |
搜尋和格式化選項
WPP 追蹤選項 | TraceWPP 命令選項 | 描述 |
---|---|---|
忽略驚嘆號 |
-noshrieks |
指示 WPP 忽略驚嘆號,也稱為「尖叫」。 用於複雜的格式設定,例如 %!timestamp!%。 根據預設,需要驚嘆號,WPP 會嘗試解譯它們。 |
格式字串編號的數值基底 |
-argbase:數位 |
建立格式字串編號的數值基底,例如 「%1!d!, %2!s!“。 預設值是 1。 |
產生追蹤訊息的函式 |
-func:FunctionDescription |
指定 DoTraceMessage 宏的替代專案。 然後,這些函式可用來產生追蹤訊息。 例如,您可以定義函式,指定追蹤訊息的旗標和層級,例如:
您可以使用 -func 選項的多個實例。 此選項指定本機組態檔中函式描述的替代方案。 |
指定要搜尋的字串 |
-lookfor:String |
指示 WPP 搜尋來源檔案,以尋找要起始追蹤的指定字串。 根據預設,WPP 會搜尋字串 「WPP_INIT_TRACING」。 這是撰寫自己範本的用戶進階選項。 例如,在 default.tpl 中:
|
指定模組名稱 |
-p: 字串 |
指定來自這個追蹤提供者之訊息之訊息 GUID 的替代易記名稱。 根據預設,訊息 GUID 的易記名稱是建立追蹤提供者所在的目錄名稱。 根據預設,訊息 GUID 的易記名稱會出現在變數 %1 所代表的追蹤訊息前置詞中。 您可以使用此參數將字串新增至前置詞,以協助使用者識別追蹤提供者,例如追蹤提供者的易記名稱、包含追蹤提供者的模組名稱,或建立數個追蹤提供者所實作的項目名稱。 這項資訊可協助使用者建立不同檔案或不同路徑中相關追蹤提供者的關聯。 -p 參數需要 Windows Vista 和更新版本的 WDK 隨附於 Windows Driver Kit (WDK) 中的 WPP 版本。 -p 參數適用於 Windows 2000 和更新版本的 Windows。 範例:
|
檔案選項
WPP 追蹤選項 | TraceWPP 命令選項 | 描述 |
---|---|---|
其他 Include 目錄 |
-I Path1[;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++和頭檔提供不同的名稱的TMH檔案,請使用 -preserveext 選項。 |
保留擴展名 |
-preserveext: .ext1[.ext2] |
建立TMH檔案時,保留指定的擴展名。 根據預設,所有文件類型的TMH檔案都會命名為 filename.tmh。 當您有多個具有相同名稱的來源檔案時,這會導致檔名衝突。 例如,根據預設,C 檔案 (.c) 和標頭 (.h) 檔案的TMH檔案會命名為 <filename.tmh>。 藉由使用 -preserveext:.c .h,TMH 檔案會命名為 <filename.c.tmh> 和 <filename.h.tmh>。 |
輸出目錄 |
-odir: path | 指定 WPP 所建立輸出檔案的目錄。 Path 是目錄的完整路徑。 預設值為本機目錄。 |
指定範本檔案 |
-gen{ File.tpl }. ext |
針對 WPP 處理的每個原始程式檔,其名稱在大括弧 {}之間指定,請建立另一個擴展名為指定的檔案。 File.tpl 代表來源檔案。 *.ext 代表建立的文件類型及其擴展名。 您可以指定多個 -gen 選項。 例如, -gen{um-default.tpl}.tmh 表示對於 WPP 處理的每個 um-default.tpl 檔案,它會產生 um-default.tmh 檔案。 |
掃描組態數據 |
-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 建置程式會完成下列步驟:
WPP 預處理器會處理每個來源檔案中的 WPP 宏,並為每個來源檔案建立 追蹤訊息頭檔 。 原始程式碼不會直接修改。
在WPP預處理器建立追蹤訊息頭文件之後,C 預處理器會以一般方式處理追蹤訊息頭檔中內建的 WPP 宏。