Добавление в реестр имен и описаний счетчиков

Статья
06/13/2023

Важно!

Из-за значительных ограничений производительности и надежности метод предоставления данных счетчиков производительности, описанный в этом разделе, может быть изменен или недоступен в будущем. Вместо этого корпорация Майкрософт рекомендует использовать метод, описанный в разделе Предоставление данных счетчика с помощью версии 2.0 , для создания новых счетчиков производительности и переноса существующих счетчиков производительности для использования этого метода.

Имена и описания всех объектов производительности версии 1 и их счетчиков должны быть установлены в системе. Чтобы сохранить имена и описания для объектов и счетчиков от поставщика версии 1, выполните следующие действия:

Создайте H-файл заголовка , содержащий символьные константы для смещений объектов и счетчиков.
Создайте файл инициализации (.INI), содержащий строки.
При установке компонента запустите средство lodctr, чтобы установить имена и описания в реестре.
При удалении компонента запустите средство unlodctr, чтобы удалить имена и описания из реестра.

Создание файла символических констант (H)

Создайте H-файл заголовка, который определяет константы (макросы) для смещений объектов и счетчиков, которые предоставляет поставщик. Заголовок .h используется в качестве входных данных для lodctr во время установки поставщика, а также может использоваться в коде C/C++ вашего поставщика.

Значения констант должны быть последовательными, четными числами, начинающиеся с нуля. Сгруппировать константы по объектам (т. е. начать каждую группу со смещением объекта, а затем следовать смещениям счетчиков для этого объекта).

Константы в заголовке определяют порядок добавления счетчиков к имени и тексту справки в реестре. Поставщик использует смещения для определения запрашиваемого объекта и значений индекса, используемых при возврате данных. Дополнительные сведения см. в разделе Реализация OpenPerformanceData.

Ниже показан пример файла символьной константы с именем CounterOffsets.h, который используется в примере создания библиотеки DLL расширения производительности .

#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] section

Раздел [info] содержит общие сведения о поставщике. Ключи разделов определяются следующим образом:

Ключ	Описание
Имя драйвера	Укажите имя ключа производительности поставщика, расположенного в реестре `HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services` в разделе . Сведения о создании этого ключа см. в статье Создание ключа производительности приложения.
SymbolFile	Укажите H-файл заголовка, содержащий символические значения объектов и счетчиков поставщика. Во время установки (при вызове lodctr) файл заголовка должен находиться в том же каталоге, что и файл .INI.
Доверенных	Если этот раздел включен в `[info]` раздел, lodctr добавит значение реестра кода проверки библиотеки в ключ производительности с двоичной сигнатурой библиотеки DLL производительности. Когда PERFLIB вызывает библиотеку DLL, она сравнивает сигнатуру с библиотекой DLL, чтобы определить, была ли она изменена. Значение доверенного ключа игнорируется.

Ключи DriverName и SymbolFile являются обязательными.

Раздел [объекты]

В [objects] разделе содержится список объектов производительности, поддерживаемых поставщиком. Используется для определения того, ссылается ли каждый символ из [text] раздела на объект или счетчик.

Для каждого объекта (набора счетчиков), поддерживаемого поставщиком, добавьте один ключ с именем <symbol>_<langid>_NAME= в [objects] раздел, где <symbol> — это имя объекта, а <langid> — идентификатор одного из поддерживаемых языков. Значение игнорируется.

Важно!

Этот [objects] раздел повышает производительность системы. Хотя раздел objects является необязательным, его всегда следует включать в файл .INI. Если включить этот раздел, библиотека DLL производительности вызывается только в том случае, если вы поддерживаете запрошенный объект. Если не включить раздел objects, библиотека DLL вызывается для каждого запроса, так как система не знает, какие объекты поддерживает ваш поставщик. Если раздел объекта не включен, lodctr создает в журнале событий приложения сообщение о том, что .INI файл не содержит раздел объектов. Идентификатор события этого сообщения — 2000.

Раздел [языки]

В [languages] этом разделе содержится список идентификаторов каждого языка, для которого поставщик предоставляет имена и строки справки. Все поставщики должны поддерживать 009 (на английском языке).

Для каждого поддерживаемого языка добавьте один ключ с именем <langid>=. Значение игнорируется, но в целях документации обычно устанавливается имя соответствующего языка, например 009=English.

Для большинства языков следует использовать идентификатор основного языка. Полный список идентификаторов языков находится в файле заголовка Winnt.h под заголовком "Идентификаторы основного языка". Преобразуйте значение, найденное в Winnt.h, в последовательность из 3 шестнадцатеричных цифр, удалив 0x префикс и добавив ведущие 0 цифры, пока последовательность не будет длиной 3 цифры. Например, чтобы указать строки на английском языке (0x9), используйте 009. Чтобы указать строки на итальянском языке (0x10), используйте 010.

Для китайского и португальского языков требуются идентификаторы основного и подязыков. Используйте 404, 804, 416 или 816 вместо 004 или 016.

Раздел [text]

В [text] разделе приводятся имена и строки справки для объектов и счетчиков.

Для каждого объекта или счетчика, а также для каждого поддерживаемого языка необходимо указать ключ NAME (содержащий имя или строку заголовка для объекта или счетчика) и при необходимости указать ключ HELP (содержащий описание или строку объяснения для объекта или счетчика). Ключи должны иметь имена <symbol>_<langid>_NAME и <symbol>_<langid>_HELP, где <symbol> — символьная константа для объекта или счетчика (как определено в H-файле символьной константы), а <langid> — это идентификатор языка, используемый для этой строки.

Например, строки на английском языке для счетчика с символом 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 (во время установки поставщика), запустите средство lodctr из папки, содержащей файл .INI и файл заголовка. Средство входит в состав компьютера. Необходимо запустить lodctr с повышенными привилегиями. Параметр lodctr — это путь к файлу .INI. Например, lodctr "C:\Program Files\MyCompany\MyProvider\MyProvider.ini".

Чтобы выгрузить имена и строки справки (во время удаления), запустите средство unlodctr . Необходимо выполнить unlodctr с повышенными привилегиями. Параметр unlodctr — это DriverName поставщика (имя ключа производительности поставщика). Например, unlodctr "MyProvider".

Перед запуском lodctr убедитесь, что в приложении есть запись в разделе Службы . Дополнительные сведения см. в статье Создание ключа производительности приложения. Если раздел не существует, lodctr не будет обновлять реестр вашими именами и описаниями.

Вместо запуска lodctr можно вызвать LoadPerfCounterTextStrings (определенный в Loadperf.h) из программы установки, чтобы загрузить описания имен счетчиков. Затем можно вызвать UnloadPerfCounterTextStrings во время удаления.

Служебная программа lodctr копирует строки из файла .INI в значения реестра Счетчики и Справка в соответствующих подразделах языка. Если соответствующий подраздел языка не существует, строки для этого языка не копируются. Служебная программа также обновляет значения последнего счетчика и последней справки . Имена и описания счетчиков производительности хранятся в следующем расположении в реестре.

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

Поделиться через