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 回调函数名称的参数。 此参数与在提供程序元素中包含 callback 属性具有相同的效果。
-migrateoutputFile	将 inputFile 清单升级到最新版本并将其保存到 outputFile，而不是生成 .h 和 .rc 文件。 此开关不能与其他开关一起使用。 用法：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，则生成的代码文件将包含以下定义，这些定义有助于对用户模式提供程序进行编码：

• 名为 prefixCounterInitialize 的提供程序初始化函数。
• 名为 prefixCounterCleanup 的提供程序清理函数。
• 一个全局 提供程序 变量，用于存储 由前缀CounterInitialize 函数打开的提供程序句柄。 变量的名称是清单中元素的 provider 属性的值symbol。 应在调用 PerfCreateInstance、 PerfDeleteInstance和其他 API 时使用此变量来控制提供程序的数据。
• 对于每个计数器集，使用 计数器集GUID 的全局计数器集 GUID 变量。 变量的名称是元素symbol的 counterSet 属性的值加上后缀“GUID”，例如 MyCounterSetGUID。 应在调用 PerfCreateInstance、 PerfDeleteInstance和其他 API 时使用此变量来控制提供程序的数据。
• 对于每个计数器 ，一个 计数器宏，其中包含计数器 id 的值。 宏的名称是元素symbol的 属性的值counter。 应在调用 PerfSetCounterRefValue、 PerfSetULongLongCounterValue和其他 API 时使用此宏来设置提供程序的数据。

在函数名称中， prefix 是指命令行参数的值 -prefix 。 -prefix如果未使用 参数，则函数将命名为 CounterInitialize 和 CounterCleanup。

在内核模式提供程序中使用生成的代码文件

CTRPP 工具将生成 .h C/C++ 代码文件。 如果提供程序清单的 providerType 属性设置为 kernelMode，则生成的代码文件将包含以下定义，这些定义有助于编码内核模式提供程序的计数器集：

• 名为 前缀RegisterCounterset 的计数器集初始化函数。 此函数填充 RegInfo 结构，然后调用 PcwRegister，将生成的计数器集注册句柄放入全局 Counterset 变量中。
• 名为 prefixUnregisterCounterset 的计数器集清理函数。 此函数对全局 Counterset 变量中的计数器集注册句柄调用 PcwUnregister。
• 名为 前缀CreateCounterset 的实例创建函数。 此函数填充 PcwData 结构的数组，然后使用全局 Counterset 变量中的计数器集注册句柄调用 PcwCreateInstance。
• 名为 prefixCloseCounterset 的实例清理函数。 此函数调用 PcwCloseInstance。
• 一个名为 前缀的实例报告函数 AddCounterset ，用于从计数器集回调函数。 此函数填充 PcwData 结构的数组，然后调用 PcwAddInstance。
• Windows SDK 20H1 及更高版本：名为前缀InitRegistrationInformationCounterset 的 RegInfo 初始化函数，用于高级方案。 此函数填充 RegInfo 结构。 当生成的 前缀RegisterCounterset 不满足你的需求时，例如，当你想要自定义 RegInfo 结构中的值或想要将返回的句柄存储在另一个变量中时，可以使用此函数。

在函数名称中， prefix 是指命令行参数的值 -prefix 。 -prefix如果未使用 参数，函数将没有前缀。

注意

具有计数器集回调时，将使用生成的前缀 Add Counterset 函数。 如果没有计数器集回调，将使用生成的 前缀CreateCounterset 和 prefixCloseCounterset 函数。

使用生成的符号文件

如果在命令行上指定 了 -ch 参数，CTRPP 工具将生成 .h 符号文件。 此文件包含提供程序中每个计数器集的名称和 GUID 的 C/C++ 符号。 编写硬编码的程序以使用 PerfLib V2 使用者函数从此计数器集中使用数据时，可以使用符号。

要求

要求	值
最低受支持的客户端	Windows Vista [仅限桌面应用]
最低受支持的服务器	Windows Server 2008 [仅限桌面应用]