向注册表添加计数器名称和说明

项目
06/13/2023

重要

由于严重的性能和可靠性限制，用于提供本主题所述的性能计数器数据的方法将来可能会更改或不可用。相反，Microsoft 建议使用使用版本 2.0 提供计数器数据中所述的方法创建新的性能计数器，并迁移现有性能计数器以使用该方法。

系统必须安装所有 V1 性能对象及其计数器的名称和说明。存储 V1 提供程序中的对象和计数器的名称和说明：

创建一个 .h 头文件，其中包含对象和计数器的偏移量的符号常量。
创建包含字符串的初始化 (.INI) 文件。
安装组件时，请运行 lodctr 工具，将名称和说明安装到注册表中。
卸载组件时，运行 unlodctr 工具以从注册表中删除名称和说明。

(.h) 文件创建符号常量

创建一个 .h 头文件，该文件定义常量 (宏) 提供程序提供的对象和计数器的偏移量。 .h 标头在提供程序安装期间用作 lodctr 的输入，并且也可以由提供程序的 C/C++ 代码使用。

常量值必须是从零开始的连续偶数。按对象对常量进行分组 (即，从每个组开始与对象偏移量，然后跟随该对象的计数器偏移量) 。

标头中的常量确定计数器添加到注册表中名称和帮助文本的顺序。提供程序使用偏移量来确定要查询的对象，以及返回数据时要使用的索引值。有关详细信息，请参阅实现 OpenPerformanceData。

下面显示了在创建性能扩展 DLL 示例中使用的名为 CounterOffsets.h 的符号常量文件的示例。

#ifndef OFFSETS_H
#define OFFSETS_H

// Symbol file that defines constant values for the objects
// and counters that the provider provides. The counters should be
// grouped by object.

#define TRANSFER_OBJECT      0 // First object must be at offset 0.
#define BYTES_SENT           2 // Counters for the object follow.
#define AVAILABLE_BANDWIDTH  4 // Offsets must be even numbers.

// Not required, but for convenience in implementing the Open function:
#define LAST_TRANSFER_OBJECT_COUNTER_OFFSET  AVAILABLE_BANDWIDTH

#define PEER_OBJECT          6 // Second object must be at the next offset.
#define BYTES_SERVED         8 // Counter for the second object.

// Not required, but for convenience in implementing the Open function:
#define LAST_PEER_OBJECT_COUNTER_OFFSET  BYTES_SERVED

#endif // OFFSETS_H

创建初始化 (.INI) 文件

初始化 (.INI) 文件包含符号文件中定义的每个对象和计数器的名称和帮助字符串。 .INI 文件在安装提供程序期间用作 lodctr 的输入。

.INI 文件应编码为 UTF-16LE (，) 字节顺序标记，并且应具有以下部分和键：

[info]
drivername=ServiceKeyName
symbolfile=SymbolFile.h
trusted=(Unused)

[objects]
<symbol>_<langid>_NAME=(Unused)

[languages]
<langid>=(Unused)

[text]
<symbol>_<langid>_NAME=Name
<symbol>_<langid>_HELP=Description

[info] 节

部分 [info] 包含有关提供程序的一般信息。分区键的定义如下：

键	说明
DriverName	指定位于注册表项下的注册表中的提供程序性能密钥的名称 `HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services` 。有关创建此密钥的信息，请参阅创建应用程序的性能密钥。
SymbolFile	指定包含提供程序对象和计数器的符号值的 .h 头文件。在安装 (调用 lodctr) 时，头文件必须与 .INI 文件位于同一目录中。
信任	如果在节中包含 `[info]` 此密钥， lodctr 将使用性能 DLL 的二进制签名向性能键添加库验证代码注册表值。当 PERFLIB 调用 DLL 时，它会将签名与 DLL 进行比较，以确定 DLL 是否已修改。受信任的密钥的值将被忽略。

DriverName和 SymbolFile 密钥是必需的。

[objects] 节

部分 [objects] 提供提供程序支持的性能对象列表。这用于确定节中的每个符号 [text] 是引用对象还是计数器。

对于提供程序) 支持的每个对象 (计数器集，请向 [objects] 节添加一个名为 <symbol>_<langid>_NAME= 的键，其中 <symbol> 是对象的名称，<langid>是受支持的语言之一的语言 ID。该值会被忽略。

重要

部分 [objects] 可提高系统的性能。尽管对象部分是可选的，但应始终在.INI文件中包含此部分。如果包含此部分，则仅当支持请求的对象时，才会调用性能 DLL。如果未包含对象部分，则会为每个查询调用 DLL，因为系统不知道提供程序支持哪些对象。如果未包含对象部分， lodctr 会在应用程序事件日志中生成一条消息，指出.INI文件不包含对象部分。此消息的事件标识符为 2000。

[languages] 节

该 [languages] 部分提供了提供程序提供名称和帮助字符串的每种语言的语言标识符列表。所有提供商都应支持 009 (英语) 。

对于每种支持的语言，请添加一个名为的 <langid>=键。该值将被忽略，但出于文档目的，该值通常设置为相应语言的名称，例如 009=English。

对于大多数语言，应使用主要语言标识符。语言标识符的完整列表位于 Winnt.h 头文件的标题“主要语言 ID”下。通过删除 0x 前缀并添加前导 0 数字，将 Winnt.h 中找到的值转换为 3 个十六进制数字序列，直到序列长度为 3 位。例如，若要指定 (0x9) 英语字符串，请使用 009。若要 (0x10) 指定意大利语字符串，请使用 010。

中文和葡萄牙语需要主语言和子语言标识符。使用 404、804、416 或 816，而不是 004 或 016。

[text] 节

部分 [text] 提供对象和计数器的名称和帮助字符串。

对于每个对象或计数器以及每种支持的语言，必须提供一个 NAME 键 (包含对象或计数器) 的名称或标题字符串，并且可以选择提供 HELP 键 (，其中包含对象或计数器) 的说明或说明字符串。键应命名为 <symbol>_<langid>_NAME 和，其中 <symbol> 是对象或计数器 (的符号常量，如符号常量 .h 文件) 中定义，是<langid>用于此<symbol>_<langid>_HELP字符串的语言标识符。

例如，带有符号 MY_COUNTER 的计数器的英语字符串将指定为：

MY_COUNTER_009_NAME=My Counter
MY_COUNTER_009_HELP=Description for My Counter.

文本键可以按任意顺序显示。文本字符串不应包含制表符等格式字符。

示例 INI 文件

下面是在创建性能扩展 DLL 示例中使用的初始化文件的示例。

[info]
drivername=MyApplication
symbolfile=CounterOffsets.h
trusted=

[objects]
TRANSFER_OBJECT_009_NAME=
PEER_OBJECT_009_NAME=

[languages]
009=English
00C=French

[text]

// English strings

TRANSFER_OBJECT_009_NAME=Transfer
TRANSFER_OBJECT_009_HELP=Provides information related to transferring files.

BYTES_SENT_009_NAME=Bytes Sent
BYTES_SENT_009_HELP=Number of bytes sent in the last transfer.

AVAILABLE_BANDWIDTH_009_NAME=Available Bandwidth
AVAILABLE_BANDWIDTH_009_HELP=Available bandwidth on the network, in bytes.

PEER_OBJECT_009_NAME=Peer
PEER_OBJECT_009_HELP=Provides information related to peer-caching.

BYTES_SERVED_009_NAME=Bytes Served
BYTES_SERVED_009_HELP=Number of bytes served from the cache.

// French strings

TRANSFER_OBJECT_00C_NAME=Transfert
TRANSFER_OBJECT_00C_HELP=Fournit des informations liées aux transferts de fichiers.

BYTES_SENT_00C_NAME=Octets Envoyés
BYTES_SENT_00C_HELP=Nombre d'octets envoyés dans le dernier transfert.

AVAILABLE_BANDWIDTH_00C_NAME=Bande Passante Disponible
AVAILABLE_BANDWIDTH_00C_HELP=Bande passante disponible sur le réseau, en octets.

PEER_OBJECT_00C_NAME=Pair
PEER_OBJECT_00C_HELP=Fournit des informations liées é mise en cache homologue.

BYTES_SERVED_00C_NAME=Octets Servis
BYTES_SERVED_00C_HELP=Le nombre d'octets servis du cache.

运行 Lodctr 工具

若要在安装提供程序) 期间加载 .INI 文件 (中定义的名称和帮助字符串，请从包含.INI文件和头文件的文件夹运行 lodctr 工具。该工具包含在计算机中。必须使用提升的权限运行 lodctr 。 lodctr 的参数是.INI文件的路径。例如，lodctr "C:\Program Files\MyCompany\MyProvider\MyProvider.ini"。

若要在卸载) 期间卸载名称和帮助字符串 (，请运行 unlodctr 工具。必须使用提升的权限运行 unlodctr 。 用于 unlodctr 的参数是提供程序的 DriverName， (提供程序的性能密钥) 的名称。例如，unlodctr "MyProvider"。

在运行 lodctr 之前，请确保应用程序在 Services 密钥下有一个条目。有关详细信息，请参阅创建应用程序的性能密钥。如果该键不存在， lodctr 将不会使用名称和说明更新注册表。

作为运行 lodctr 的替代方法，可以从安装程序调用 Loadperf.h) 中定义的 LoadPerfCounterTextStrings (，以加载计数器名称说明。然后，可以在卸载期间调用 UnloadPerfCounterTextStrings 。

lodctr 实用工具将字符串从 .INI 文件复制到相应语言子项下的 Counters 和 Help 注册表值。如果相应的语言子项不存在，则不会复制该语言的字符串。该实用工具还会更新“ 最后一个计数器 ”和“ 上次帮助” 值。性能计数器名称和说明存储在注册表的以下位置。

HKEY_LOCAL_MACHINE
   \SOFTWARE
      \Microsoft
         \Windows NT
            \CurrentVersion
               \Perflib
                  Last Counter = highest counter index
                  Last Help = highest help index
                  \009
                     Counters = 2 System 4 Memory...
                     Help = 3 The System Object Type...
                  \supported language, other than English
                     Counters = ...
                     Help = ...

除了在 PerfLib 键下添加值外， lodctr 工具还会将以下值添加到应用程序的 “服务” 节点。在大多数情况下，应用程序和提供程序将具有一对一关系;但是，提供程序可以为多个应用程序提供计数器数据，这就是为什么密钥基于应用程序而不是提供程序的原因。

HKEY_LOCAL_MACHINE
   \SYSTEM
      \CurrentControlSet
         \Services
            \MyApplication
               \Performance
                  First Counter = lowest counter index assigned to provider
                  First Help = lowest help index assigned to provider
                  Last Counter = highest counter index assigned to provider
                  Last Help = highest help index assigned to provider
                  Object List = list of object index values if the .INI includes the [objects] section
                  Library Validation Code = if the [info] section contains a "trusted" key