レジストリへのカウンター名と説明の追加

[アーティクル]
06/13/2023

重要

パフォーマンスと信頼性の大幅な制限により、このトピックで説明するパフォーマンスカウンターデータを提供する方法は、今後変更または使用できない可能性があります。代わりに、「バージョン 2.0 を使用してカウンターデータを提供する」で説明されている方法を使用して新しいパフォーマンスカウンターを作成し、その方法を使用するように既存のパフォーマンスカウンターを移行することをお勧めします。

すべての V1 パフォーマンスオブジェクトとそのカウンターの名前と説明は、システムにインストールする必要があります。 V1 プロバイダーのオブジェクトとカウンターの名前と説明を格納するには:

オブジェクトとカウンターへのオフセットのシンボリック定数を含む .h ヘッダーファイルを作成します。
文字列を含む初期化 (.INI) ファイルを作成します。
コンポーネントをインストールするときは、lodctr ツールを実行して、レジストリに名前と説明をインストールします。
コンポーネントをアンインストールするときは、unlodctr ツールを実行して、レジストリから名前と説明を削除します。

シンボリック定数 (.h) ファイルの作成

プロバイダーが提供するオブジェクトとカウンターへのオフセットの定数 (マクロ) を定義する .h ヘッダーファイルを作成します。 .h ヘッダーは、プロバイダーのインストール時に lodctr への入力として使用され、プロバイダーの C/C++ コードでも使用できます。

定数値は、0 から始まる偶数の連続する値である必要があります。定数をオブジェクト別にグループ化します (つまり、各グループをオブジェクトオフセットで開始し、そのオブジェクトのカウンターのオフセットに従います)。

ヘッダーの定数によって、レジストリ内の名前とヘルプテキストにカウンターが追加される順序が決まります。プロバイダーは、オフセットを使用して、クエリ対象のオブジェクトと、データを返すときに使用するインデックス値を決定します。詳細については、「 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] 各シンボルがオブジェクトまたはカウンターを参照しているかどうかを判断するために使用されます。

プロバイダーでサポートされているオブジェクト (カウンターセット) ごとに、セクションにという名前 <symbol>_<langid>_NAME= の 1 つのキーを [objects] 追加します。ここで <symbol> 、はオブジェクトの名前で、 <langid> サポートされている言語の 1 つの言語 ID です。値は無視されます。

重要

セクションでは [objects] 、システムのパフォーマンスが向上します。 objects セクションは省略可能ですが、.INI ファイルには常にこのセクションを含める必要があります。このセクションを含める場合、要求されたオブジェクトをサポートしている場合にのみ、パフォーマンス DLL が呼び出されます。 objects セクションを含まない場合、プロバイダーがサポートするオブジェクトがシステムで認識されないため、すべてのクエリに対して DLL が呼び出されます。オブジェクトセクションが含まれていない場合、 lodctr は、.INI ファイルにオブジェクトセクションが含まれていないことを示すメッセージをアプリケーションイベントログに生成します。このメッセージのイベント識別子は 2000 です。

[言語] セクション

セクションでは [languages] 、プロバイダーが名前とヘルプ文字列を提供する各言語の言語識別子の一覧を示します。すべてのプロバイダーが (英語) をサポート 009 する必要があります。

サポートされている言語ごとに、という名前 <langid>=のキーを 1 つ追加します。値は無視されますが、ドキュメントの目的では、通常、値は対応する言語の名前 (例: ) に設定されます。 009=English

ほとんどの言語では、プライマリ言語識別子を使用する必要があります。言語識別子の完全な一覧は、Winnt.h ヘッダーファイルの見出し "プライマリ言語 ID" にあります。Winnt.h で見つかった値を 3 桁の 16 進数のシーケンスに変換します。プレフィックスを 0x 削除し、シーケンスの長さが 3 桁になるまで先頭 0 の数字を追加します。たとえば、英語の文字列 (0x9) を指定するには、009 を使用します。イタリア語の文字列 (0x10) を指定するには、010 を使用します。

中国語とポルトガル語では、プライマリ識別子とサブ言語識別子の両方が必要です。 004 または 016 ではなく、404、804、416、または 816 を使用します。

[text] セクション

セクションには [text] 、オブジェクトとカウンターの名前とヘルプ文字列が表示されます。

各オブジェクトまたはカウンター、およびサポートされている言語ごとに、NAME キー (オブジェクトまたはカウンターの名前またはタイトル文字列を含む) を指定する必要があります。また、必要に応じて HELP キー (オブジェクトまたはカウンターの説明または説明文字列を含む) を指定することもできます。キーにはと <symbol>_<langid>_HELPという名前を付<symbol>_<langid>_NAMEける必要があります。ここで<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 ファイルに定義されている名前とヘルプ文字列を読み込むには、.INI ファイルとヘッダーファイルを含むフォルダーから lodctr ツールを実行します。このツールはコンピューターに含まれています。管理者特権で 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 ファイルから適切な言語サブキーの下にある 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 ツールはアプリケーションの [サービス] ノードにも次の値を追加します。ほとんどの場合、アプリケーションとプロバイダーには 1 対 1 のリレーションシップがあります。ただし、プロバイダーが複数のアプリケーションのカウンターデータを提供することは可能です。そのため、キーはプロバイダーではなくアプリケーションに基づいています。

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

次の方法で共有