本節說明 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 追蹤屬性頁面，或作為 TraceWPP 工具的參數，在 Visual Studio 中設定這些選項。
| WPP 追蹤選項 | 說明 |
|---|---|
執行 WPP |
如果為True，則調用WPP。 |
啟用最小重建 |
如果為true，則會執行追蹤的累加式建置;如果為 false，則會執行重建。 |
函數和巨集選項
| WPP 追蹤選項 | TraceWPP 命令選項 | 說明 |
|---|---|---|
前置處理器定義 |
-D巨集 |
將 #define巨集 新增至產生檔案的開頭，其中 巨集 是巨集的名稱。 此選項與 /D （定義巨集） 編譯器選項具有相同的效果。 為了確保在 TMH 檔案開頭的定義是有效的，包含了這個項目。 |
-D宏擴展= |
將 #define巨集擴充 新增至所產生檔案的開頭，其中 巨集 是巨集的名稱，而 擴充 是展開的值。 此選項與 /D （定義巨集） 編譯器選項具有相同的效果。 包含它是為了確保定義項在 TMH 檔案的開頭有效。 |
|
追蹤 Kernel-Mode 元件 |
-公里 |
定義WPP_KERNEL_MODE巨集，以追蹤核心模式元件。 根據預設，只會追蹤使用者模式元件。 |
啟用 DLL 巨集 |
-dll 檔案 |
定義 WPP_DLL 巨集，這會使得每當呼叫 WPP_INIT_TRACING 時，WPP 資料結構就會被初始化。 否則，結構只會初始化一次。 |
指定控制代碼 GUID |
-ctl：GUID |
定義一個WPP_CONTROL_GUIDS宏，其中包含指定的控制項 GUID 和被命名為 Error, Unusual, 和 Noise 的 WPP_DEFINE_BIT 條目。
這是將巨集新增至來源檔案的替代方法。 GUID 代表控制項 GUID。 |
搜尋和格式選項
| WPP 追蹤選項 | TraceWPP 命令選項 | 說明 |
|---|---|---|
忽略感嘆號 |
-鼻尖叫 |
指示 WPP 忽略感嘆號，也稱為「驚嘆號」。 用於複雜的格式，例如 %！timestamp！%。 根據預設，需要驚嘆號，WPP 會嘗試解譯它們。 |
格式字串編號的數值基數 |
-argbase：數字 |
建立格式字串編號的數值基數，例如「%1！d！、%2！s！」。 預設值為 1。 |
產生追蹤訊息的功能 |
-func：函數說明 |
指定 DoTraceMessage 巨集的替代方案。 然後，這些函數可用來產生追蹤訊息。 例如，您可以定義一個函數，以指定追蹤訊息的旗標和層次，例如： 您可以使用 -func 選項的多個實例。 此選項是在本端配置檔中指定功能說明的替代方法。 |
指定要搜尋的字串 |
-lookfor：字串 |
指示 WPP 在來源檔案中搜尋指定的字串，以起始追蹤。 根據預設，WPP 會搜尋字串 “WPP_INIT_TRACING”。 對於正在編寫自己的模板的用戶來說，這是一個高級選項。 例如，在 default.tpl 中： |
指定模組名稱 |
-p：字串 |
指定來自此追蹤提供者之訊息 GUID 的替代易記名稱。 根據預設，訊息 GUID 的易記名稱是建置追蹤提供者的目錄名稱。 根據預設，訊息 GUID 的易記名稱會出現在變數所代表的 追蹤訊息前置詞 中， %1。 您可以使用此參數將字串新增至前置詞，以協助使用者識別追蹤提供者，例如追蹤提供者的易記名稱、包含追蹤提供者的模組名稱，或建立數個追蹤提供者所實作的專案名稱。 此資訊可協助使用者關聯位於不同檔案或不同路徑中的相關追蹤提供者。 -p 參數需要 WPP 版本，此版本包含在適用於 Windows Vista 及更新版本的 Windows 驅動程式套件（WDK）中。 -p 參數適用於 Windows 2000 和更新版本的 Windows。 範例： |
檔案選項
| WPP 追蹤選項 | TraceWPP 命令選項 | 說明 |
|---|---|---|
其他 Include 目錄 |
-I路徑 1[;路徑2] |
指定一或多個要加入 Include 路徑中的目錄；如有多個目錄，請使用分號加以分隔。 與 -cfgdir 相同。 |
組態目錄 |
-cfgdir：路徑1[;路徑2] |
指定組態和範本檔案的位置。 Path1 和 Path2 代表目錄的完整路徑。 您可以指定多個路徑。 預設值為本機目錄。 |
擴展名 |
-ext:.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：路徑 | 指定 WPP 所建立之輸出檔案的目錄。 路徑 是目錄的完整路徑。 預設值為本機目錄。 |
指定範本檔案 |
-gen{ 檔案.tpl }。副檔名 |
針對 WPP 處理的每個來源檔案，其名稱指定在大括弧 {}之間，建立另一個具有指定副檔名的檔案。 File.tpl 代表來源檔案。 *.ext 代表所建立的檔案類型及其副檔名。 您可以指定多個 -gen 選項。 例如， -gen{um-default.tpl}.tmh 表示針對 WPP 處理的每個 um-default.tpl 檔案，它會產生 um-default.tmh 檔案。 |
掃描組態資料 |
-scan：檔案 |
在非組態檔的檔案中搜尋組態資料，例如自訂資料型別，以及在 defaultwpp.ini中。 在組態設定資料周圍放置 begin_wpp config 和 end_wpp 字串以識別它。 使用與 defaultwpp.ini中使用的配置資料相同的格式。 如果您將組態資料新增至自訂組態檔，請使用 -ini 參數。 |
替代組態檔 |
-defwpp：路徑 |
指定替代組態檔。 Wpp 使用此檔案而不是 defaultwpp.ini 檔案。 |
其他組態檔 |
-ini：路徑 |
指定其他組態檔。 WPP 除了使用預設檔案之外，還會使用指定的檔案 defaultwpp.ini。 當您建立新的組態檔來儲存要追蹤的組態資料時，請使用此參數。 如果您已將配置資料新增至其他類型的檔案 （例如來源或標頭檔），請使用 -scan 參數。 |
WPP 建置程式
如果已針對驅動程式或使用者模式應用程式啟用 WPP，則建置驅動程式或應用程式會在編譯驅動程式或應用程式檔案之前叫用 WPP 前置處理器。
WPP 建置程式會完成下列步驟：
WPP 前置處理器會處理每個來源檔案中的 WPP 宏，並為每個來源檔案建立 追蹤訊息標頭檔 。 原始碼不會直接修改。
WPP 前置處理器建立追蹤訊息標頭檔之後，C 前置處理器會以正常方式處理追蹤訊息標頭檔中的內建 WPP 宏。