CTRPP
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++ シンボルが含まれます。 |
| -prefixprefix | 生成されたヘッダー ファイルで定義されている変数と関数に使用するプレフィックスを指定します。 |
| -NotificationCallback |
CounterInitialize 関数の既定のシグネチャを変更して、ControlCallback、AllocateMemory、FreeMemory コールバック関数の名前を指定するためのパラメーターを含めます。 この引数は、provider 要素に 属性をcallback含めると同じ効果があります。 |
| -migrateoutputFile | と .rc ファイルを生成する.h代わりに、inputFile マニフェストを最新バージョンにアップグレードし、outputFile に保存します。 このスイッチは、他のスイッチでは使用できません。 使用法: CTRPP -migrate NewFile.man OldFile.man |
| -BackCompat |
廃止： カーネル モード プロバイダーのサポートが Windows 7 で追加されました。 既定では、カーネル モード プロバイダー用に CTRPP によって生成されたコードは、以前のバージョンの Windows と互換性がありません (API がないため、ドライバーの読み込みに Pcw*** 失敗します)。 以前のバージョンの Windows との互換性を有効にするには、 を設定 -BackCompat します。 ドライバーは必要な API を動的に読み込み、API が使用できない場合は、生成されたコードによってプロバイダーが自動的に無効になります。 |
| -MemoryRoutines |
廃止： スイッチと共に使用する -Legacy 場合は、生成されたコードにメモリ ルーチンのテンプレートが含まれます。 それ以外の場合、この引数はスイッチと同じ効果を持 -NotificationCallback ちます。 |
| -レガシー |
廃止：*.hWindows Vista コード テンプレートを使用して、、*.c、*.rc、および *_r.h ファイルを生成します (CounterInitialize と CounterCleanup の代わりに PerfAutoInitialize と PerfAutoCleanup が生成されます)。 このスイッチは -MemoryRoutines および -NotificationCallback と共に使用できますが、他のスイッチでは使用できません。 このスイッチでは 、-o スイッチまたは -rc スイッチを使用しないでください。 生成されたファイルは、マニフェストの名前に基づいて名前が付けられ、マニフェストを含むディレクトリに書き込まれます。 使用法: CTRPP -legacy OldFile.man |
注釈
CTRPP ツールは、コード ファイル、リソース ファイルを.rc生成.hし、必要に応じてシンボル ファイルを.h生成します。
生成されたリソース ファイルの使用
CTRPP ツールは、プロバイダーのカウンターセットのコンシューマーが必要とするローカライズ可能な文字列を含むリソース ファイルを生成 .rc します。
重要
このファイルのリソースはプロバイダー バイナリに含める必要があり、プロバイダー のマニフェストのインストール中にプロバイダー バイナリへの完全なパスを登録する必要があります。 リソースを見つけて読み込むことができないコンシューマーは、プロバイダーのカウンターセットを使用できません。
文字列リソースは、次のように処理する必要があります。
- 開発者はプロバイダー マニフェスト (
.man) ファイルを編集して、プロバイダーの属性を、プロバイダーの文字列リソースを含み、プロバイダー コンポーネントの一部としてインストールされるプロバイダー バイナリ (.DLL、.SYS、または.EXE) の名前に設定applicationIdentityします。 - 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 ツールは C/C++ コード ファイルを .h 生成します。 プロバイダー マニフェストの 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 参照します。 パラメーターが-prefix使用されていない場合、関数には と という名前が付CounterCleanupけられますCounterInitialize。
カーネル モード プロバイダーで生成されたコード ファイルを使用する
CTRPP ツールは C/C++ コード ファイルを .h 生成します。 プロバイダー マニフェストの providerType 属性が に kernelMode設定されている場合、生成されたコード ファイルには、カーネル モード プロバイダーのカウンターセットのコーディングに役立つ次の定義が含まれます。
- プレフィックスRegisterCounterset という名前のカウンターセット初期化関数。 この関数は RegInfo 構造体を入力し、 PcwRegister を呼び出し、結果として得られるカウンターセット登録ハンドルをグローバル Counterset 変数に格納します。
- prefixUnregisterCounterset という名前のカウンターセット クリーンアップ関数。 この関数は、グローバル Counterset 変数のカウンターセット登録ハンドルで PcwUnregister を呼び出します。
- プレフィックスCreateCounterset という名前のインスタンス作成関数。 この関数は、PcwData 構造体の配列を入力し、グローバル Counterset 変数のカウンターセット登録ハンドルを使用して PcwCreateInstance を呼び出します。
- プレフィックスCloseCounterset という名前のインスタンス クリーンアップ関数。 この関数は 、PcwCloseInstance を呼び出します。
- カウンターセット コールバック関数から使用される プレフィックスAddCounterset という名前のインスタンス レポート関数。 この関数は 、PcwData 構造体の配列を入力し、 PcwAddInstance を呼び出します。
- Windows SDK 20H1 以降: 高度なシナリオで使用するための プレフィックスInitRegistrationInformationCounterset という名前の RegInfo 初期化関数。 この関数は 、RegInfo 構造体を入力します。 この関数は、生成された プレフィックスRegisterCounterset がニーズを満たさない場合 (RegInfo 構造体の値をカスタマイズする場合や、返されたハンドルを別の変数に格納する場合など) に使用できます。
関数名では、 prefix はコマンド ライン パラメーターの値を -prefix 参照します。 パラメーターが -prefix 使用されていない場合、関数にはプレフィックスはありません。
注意
生成された プレフィックスAddCounterset 関数は、カウンターセット コールバックがある場合に使用されます。 生成された プレフィックスCreateCounterset 関数と プレフィックスCloseCounterset 関数は、カウンターセット コールバックがない場合に使用されます。
生成されたシンボル ファイルの使用
コマンド ラインで -ch パラメーターを指定すると、CTRPP ツールによってシンボル ファイルが .h 生成されます。 このファイルには、プロバイダー内の各カウンターセットの名前と GUID の C/C++ シンボルが含まれています。 シンボルは、 PerfLib V2 Consumer 関数を使用して、このカウンターセットのデータを使用するようにハードコーディングされたプログラムを作成するときに使用できます。
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows Vista [デスクトップ アプリのみ] |
| サポートされている最小のサーバー | Windows Server 2008 [デスクトップ アプリのみ] |