CTRPP

CTRPP 工具是一個預處理器，用於分析和驗證 V2 提供程式的清單。 該工具使用提供程式的消費者所需的字串生成 .rc 資源，並使用用於提供計數器數據的代碼生成 .h 標頭。 您應該在建構提供程式期間執行 CTRPP 工具。 在開發提供程式時，您應該使用生成的代碼作為起點，而不是嘗試自己生成此代碼。

ctrpp -o codeFile -rc rcFile [-legacy] [-MemoryRoutines] [-NotificationCallback] [-prefix prefix] [-ch symFile] [-backcompat] inputFile

論點

備註

CTRPP 工具生成代碼 .h 檔、資源 .rc 檔，並選擇性地生成符號 .h 檔。

使用生成的資源檔

CTRPP 工具將生成一個 .rc 資源檔，其中包含提供程式計數器集的消費者所需的可當地語系化字串。

字串資源應按如下方式處理：

• 開發人員編輯提供程式清單 （）.man 檔案，將提供程式的屬性設置為 applicationIdentity 提供程式二進位檔（.DLL、.SYS 或 .EXE）的名稱，該二進位檔將包含提供程式的字串資源，並將作為提供程式元件的一部分進行安裝。
• CTRPP 工具讀取提供程式清單並生成檔 .rc 。
• RC （資源編譯器） 工具編譯 CTRPP 產生的.rc文件中的數據，以生成.res包含二進位資源的檔。 這可以通過直接編譯 CTRPP 生成的.rc檔或通過指令編譯包含 CTRPP 生成的.rc檔#include的另一個.rc檔來完成。
• 鏈接器將 RC 產生的 .res 檔案中的數據嵌入到提供程式二進位檔中。
• 在安裝過程中，提供程式二進位檔將複製到用戶的系統上，並使用 lodctr工具註冊提供程式清單。 lodctr 工具將 applicationIdentity 提供程式清單的屬性轉換為完整路徑，並在註冊表中記錄提供程式二進位檔的完整路徑。
  • 如果提供者二進位檔案與清單位於同一目錄中，請使用： lodctr.exe /m:"C:\full\manifest\path\manifest.man"。 LODCTR 會將指定的清單路徑與清單的屬性 applicationIdentity 組合在一起，以形成完整路徑。
  • 否則，請使用 lodctr.exe /m:"C:\full\manifest\path\manifest.man" "c:\full\binary\path"。 LODCTR 會將指定的二進位路徑與 manifest 的屬性 applicationIdentity 組合在一起，以形成完整路徑。
  • 出於診斷目的，您可以通過檢查 ApplicationIdentity registry key HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Perflib\_V2Providers\{<ProviderGuid>}的值來檢查記錄的完整路徑。
  • 如果二進位檔使用 MUI 進行當地語系化，請務必將 MUI 檔與二進位檔一起複製。
• 在計數器集收集期間，消費者使用記錄的提供者二進位檔的完整路徑從提供者二進位檔的資源中查找和載入必要的字串。

在使用者模式提供程式式中使用生成的代碼檔

CTRPP 工具將生成 .h C/C++ 程式碼檔。 如果提供程式清單的屬性 providerType 設定為 userMode，則生成的代碼檔將包含以下定義，這些定義有助於對使用者模式提供程式進行編碼：

• n 名為 prefixCounterInitialize 的提供程式初始化函數。
• 名為 prefixCounterCleanup 的提供程式清理函數。
• 一個全域 提供程式 變數，用於存儲 由前綴CounterInitialize 函數打開的提供程式句柄。 變數的 name 是清單中元素的屬性provider值symbol。 此變數應用於對 PerfCreateInstance、 PerfDeleteInstance和其他 API 的呼叫，以控制供應商的數據。
• 對於每個計數器集，一個具有計數器集 GUID 的全域 計數器集GUID 變數。 變數的名稱是元素屬性的值counterSet加上後綴 「GUID」 例如 MyCounterSetGUID.symbol 此變數應用於對 PerfCreateInstance、 PerfDeleteInstance和其他 API 的呼叫，以控制供應商的數據。
• 對於每個計數器，一個具有counter id 值的counter 巨集。 巨集的 name 是元素屬性symbol的值counter。 此巨集應用於對 PerfSetCounterRefValue、 PerfSetULongLongCounterValue和其他 API 的呼叫，以設置提供程式的數據。

在函數名稱中， prefix 是指命令行參數的值 -prefix 。 如果未使用該參數， -prefix 則函數將被命名為 CounterInitialize 和 CounterCleanup。

在內核模式提供程式式中使用生成的代碼檔

CTRPP 工具將生成 .h C/C++ 程式碼檔。 如果提供程式清單的屬性 providerType 設定為 kernelMode，則生成的代碼檔將包含以下定義，這些定義有助於對內核模式提供程式的計數器集進行編碼：

• 名為 prefixRegisterCounterset 的計數器集初始化函數。 此函數填充 RegInfo 結構，然後調用 PcwRegister，將生成的計數器集註冊句柄放入全域 Counterset 變數中。
• 名為 prefixUnregisterCounterset 的計數器集清理函數。 此函數在全域 Counterset 變數中的計數器集註冊句柄上調用 PcwUnregister。
• 名為 prefixCreateCounterset 的實例創建函數。 此函數填充 PcwData 結構數位，然後使用全域 Counterset 變數中的計數器集註冊句柄調用 PcwCreateInstance 。
• 名為 prefixCloseCounterset 的實例清理函數。 此函數調用 PcwCloseInstance。
• 名為 prefixAddCounterset 的實例報告函數，用於 counterset 回調函數。 此函數填充 PcwData 結構數位，然後調用 PcwAddInstance。
• Windows SDK 20H1 及更高版本： 名為 prefixInitRegistrationInformationCounterset 的 RegInfo 初始化函數，用於高級方案。 此函數填充 RegInfo 結構。 此函數可用於生成的 前綴RegisterCounterset 無法滿足您的需求的情況，例如，當您想要自定義 RegInfo 結構中的值或要將返回的句柄存儲在另一個變數中時。

在函數名稱中， prefix 是指命令行參數的值 -prefix 。 如果未使用該 -prefix 參數，則函數將沒有前綴。

使用生成的元件檔

如果在命令行上指定了 -ch 參數，則 CTRPP 工具將生成一個 .h 符號檔。 此檔案包含提供程式中每個計數器集的名稱和 GUID 的 C/C++ 符號。 編寫硬編碼的程式以使用 PerfLib V2 使用者函數使用此計數器集中的數據時，可以使用這些符號。

需求