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 使用者函数使用此计数器集中的数据时，可以使用这些符号。

要求