CTRPP

發行項
06/13/2023

CTRPP 工具是一種前置處理器，可剖析並驗證 V2 提供者的資訊清單。此工具會 .rc 使用提供者取用者所需的字串產生資源，並產生 .h 標頭，其中包含您用來提供計數器資料的程式碼。您應該在提供者的組建期間執行 CTRPP 工具。開發提供者時，您應該使用產生的程式碼作為起點，而不是自行嘗試產生此程式碼。

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

引數

選項	描述
inputFile	必填：指定定義計數器之 `.man` (XML 資訊清單) 檔的名稱。
-ocodeFile	必填：指定要由 CTRPP 產生之程式碼檔的名稱 `.h` 。此檔案將包含 C/C++ 內嵌協助程式函式，可簡化提供者的初始化和取消初始化。
-rcrcFile	必填：指定要由 CTRPP 產生之 (資源檔的名稱 `.rc`) 。此檔案將包含提供者的字串資料表。
-chsymFile	指定要由 CTRPP 產生之選擇性 `.h` 符號檔的名稱。此檔案會包含提供者中每個計數器集名稱和 GUID 的 C/C++ 符號。
-prefix 前置詞	指定要用於所產生標頭檔中所定義之變數和函式的前置詞。
-NotificationCallback	變更CounterInitialize函式的預設簽章，以包含參數，以指定ControlCallback、AllocateMemory 和 FreeMemory回呼函式的名稱。這個引數的效果與在 `callback`提供者元素中包含屬性相同。
-migrateoutputFile	不要產生 `.h` 和 `.rc` 檔案，而是將 inputFile 資訊清單升級至最新版本，並將它儲存至 outputFile。這個參數無法與其他參數搭配使用。使用方式：`CTRPP -migrate NewFile.man OldFile.man`
-BackCompat	廢棄： Windows 7 已新增核心模式提供者的支援。根據預設，CTRPP 針對核心模式提供者所產生的程式碼會與舊版 Windows (驅動程式不相容，因為遺漏 `Pcw***` API) 而無法載入。設定 `-BackCompat` 為啟用與舊版 Windows 的相容性。驅動程式會動態載入必要的 API，如果 API 無法使用，產生的程式碼將會以無訊息方式停用提供者。
-MemoryRoutines	廢棄：搭配 `-Legacy` 參數使用時，在產生的程式碼中包含記憶體常式的範本。否則，這個引數的效果與參數相同 `-NotificationCallback` 。
-遺產	廢棄：`.h`使用 Windows Vista 程式碼範本產生、 `.c` 、 `.rc` 和 `_r.h` 檔案， (產生 PerfAutoInitialize 和 PerfAutoCleanup，而不是 CounterInitialize 和 CounterCleanup) 。此參數可以搭配 -MemoryRoutines 和 -NotificationCallback 使用，但無法搭配任何其他參數使用。請勿搭配此參數使用 -o 或 -rc 參數。產生的檔案會根據資訊清單的名稱命名，並且會寫入包含資訊清單的目錄。使用方式：`CTRPP -legacy OldFile.man`

備註

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

使用產生的資源檔

CTRPP 工具會產生 .rc 資源檔，其中包含提供者計數器集取用者所需的可當地語系化字串。

重要

此檔案中的資源必須包含在提供者二進位檔中，而且提供者二進位檔的完整路徑必須在提供者資訊清單安裝期間註冊。找不到並載入資源的取用者將無法使用提供者的計數器集。

字串資源應該以下列方式處理：

開發人員會編輯提供者資訊清單 (.man) 檔案，將提供者的屬性設定 applicationIdentity 為提供者二進位檔 (.DLL、.SYS或.EXE) ，其中包含提供者的字串資源，並將安裝為提供者元件的一部分。
CTRPP 工具會讀取提供者資訊清單並產生檔案 .rc 。
RC (資源編譯器) 工具會從 CTRPP 產生的 .rc 檔案編譯資料，以產生 .res 包含二進位資源的檔案。這可以藉由直接編譯 CTRPP 產生的 .rc 檔案，或透過指示詞編譯包含 CTRPP 產生的 .rc 檔案的另一個 .rc#include 檔案來完成。
連結器會將 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 會將指定的二進位路徑與資訊清單的 applicationIdentity 屬性結合，以形成完整的路徑。
- 基於診斷目的，您可以藉由檢查登錄機碼 HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Perflib\_V2Providers\{<ProviderGuid>} 的值來檢查 ApplicationIdentity 記錄的完整路徑。
- 如果二進位檔使用 MUI 進行當地語系化，請務必複製 MUI 檔案以及二進位檔。
在計數器集集合期間，取用者會使用提供者二進位檔的完整路徑，從提供者二進位資源尋找並載入必要的字串。

在使用者模式提供者中使用產生的程式碼檔案

CTRPP 工具會產生 .h C/C++ 程式碼檔案。如果提供者資訊清單的 providerType 屬性設定 userMode 為，則產生的程式碼檔案將包含下列定義，有助於撰寫使用者模式提供者的程式碼：

名為CounterInitialize前置詞的提供者初始化函式。
名為CounterCleanup前置詞的提供者清除函式。
全域 提供者 變數，儲存 前置詞 CounterInitialize 函式所開啟的提供者控制碼。變數的名稱是 symbol 資訊清單中元素的 provider 屬性值。此變數應該用於對 PerfCreateInstance 、 PerfDeleteInstance 和其他 API 的呼叫，以控制提供者的資料。
針對每個計數器集，具有計數器集 GUID 的全域 計數器集GUID 變數。變數的名稱是元素 symbol 屬性的值 counterSet 加上後置詞「GUID」，例如。 MyCounterSetGUID 此變數應該用於對 PerfCreateInstance 、 PerfDeleteInstance 和其他 API 的呼叫，以控制提供者的資料。
針對每個計數器，具有計數器 id 值的計數器宏。宏的名稱是專案 symbol 屬性的值 counter 。此宏應該用於呼叫 PerfSetCounterRefValue 、 PerfSetULongLongCounterValue 和其他 API，以設定提供者的資料。

在函式名稱中，前置詞是指命令列參數的值 -prefix 。 -prefix如果未使用參數，函式將會命名 CounterInitialize 為和 CounterCleanup 。

在核心模式提供者中使用產生的程式碼檔案

CTRPP 工具會產生 .h C/C++ 程式碼檔案。如果提供者資訊清單的 providerType 屬性設定 kernelMode 為，則產生的程式碼檔案將包含下列定義，有助於撰寫核心模式提供者計數器集的程式碼：

名為RegisterCounterset前置詞的計數器集初始化函式。此函式會填入 RegInfo 結構，然後叫用 PcwRegister，並將產生的計數器集注冊控制碼放入全域 Counterset 變數。
名為prefixUnregisterCounterset的計數器集清除函式。此函式會在全域Counterset變數的計數器集注冊控制碼上叫用PcwUnregister。
名為CreateCounterset前置詞的實例建立函式。此函式會填入PcwData結構的陣列，然後使用全域Counterset變數中的計數器集注冊控制碼叫用PcwCreateInstance。
名為CloseCounterset前置詞的實例清除函式。此函式會叫用 PcwCloseInstance。
名為AddCounterset前置詞的實例報告函式，用於計數器集回呼函式。此函式會填入 PcwData 結構的陣列，然後叫用 PcwAddInstance。
Windows SDK 20H1 和更新版本：名為prefixInitRegistrationInformationCounterset的 RegInfo初始化函式，用於進階案例。此函式會填入 RegInfo 結構。如果產生的前置詞RegisterCounterset不符合您的需求，例如，當您想要自訂 RegInfo 結構中的值，或想要將傳回的控制碼儲存在另一個變數中時，可以使用此函式。

在函式名稱中，前置詞是指命令列參數的值 -prefix 。 -prefix如果未使用參數，函式就不會有前置詞。

注意

當您有計數器集回呼時，會使用產生的前置詞AddCounterset函式。當您沒有計數器集回呼時，會使用產生的前置詞CreateCounterset和prefixCloseCounterset函式。

使用產生的符號檔

如果在命令列上指定 了 -ch 參數，CTRPP 工具將會產生 .h 符號檔。此檔案包含提供者中每個計數器集名稱和 GUID 的 C/C++ 符號。當撰寫硬式編碼的程式，以使用 PerfLib V2 消費者函式從這個計數器集取用資料時，可以使用符號。

規格需求

需求	值
最低支援的用戶端	Windows Vista [僅限傳統型應用程式]
最低支援的伺服器	Windows Server 2008 [僅限傳統型應用程式]

Share via