將計數器名稱和描述新增至登錄

發行項
06/13/2023

重要

由於顯著的效能和可靠性限制，提供本主題描述的效能計數器資料的方法未來可能會改變或無法使用。相反地，Microsoft 建議您使用使用 2.0 版提供計數器資料中所述的方法來建立新的效能計數器，並移轉現有的效能計數器以使用該方法。

所有 V1 效能物件及其計數器的名稱和描述都必須安裝系統。若要從 V1 提供者儲存物件和計數器的名稱和描述：

建立 .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] 區段

區 [info] 段包含提供者的一般資訊。區段索引鍵的定義如下：

Key	描述
DriverName	指定位於機碼下 `HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services` 登錄中提供者效能金鑰的名稱。如需建立此金鑰的資訊，請參閱建立應用程式的效能金鑰。
SymbolFile	指定 .h 標頭檔，其中包含提供者物件和計數器的符號值。在叫用 lodctr) 時，安裝 (期間，標頭檔必須位於與.INI檔案相同的目錄中。
信任	如果您在區段中包含此機 `[info]` 碼， lodctr 會使用效能 DLL 的二進位簽章，將程式庫驗證碼登錄值新增至您的效能金鑰。當 PERFLIB 呼叫 DLL 時，它會比較簽章與您的 DLL，以判斷 DLL 是否已修改。會忽略 Trusted索引鍵的值。

DriverName和 SymbolFile 索引鍵是必要的。

[objects] 區段

區 [objects] 段提供提供者支援的效能物件清單。這是用來判斷區 [text] 段中的每個符號是否參考物件或計數器。

針對提供者所支援的每個物件 (計數器集) ，請將一個名為 <symbol>_<langid>_NAME= 的索引鍵新增至 [objects] 區段，其中 <symbol> 是物件的名稱，而 <langid> 是其中一種支援語言的語言識別項。值會被忽略。

重要

區 [objects] 段可改善系統的效能。雖然物件區段是選擇性的，但您應該一律將此區段包含在您的.INI檔案中。如果您包含本節，只有在支援要求的物件時，才會呼叫您的效能 DLL。如果您未包含 objects 區段，系統會針對每個查詢呼叫您的 DLL，因為系統不知道您的提供者支援哪些物件。如果未包含物件區段， lodctr 會在應用程式事件記錄檔中產生訊息，指出.INI檔案未包含物件區段。此訊息的事件識別碼為 2000。

[languages] 區段

區 [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] 段會提供物件和計數器的名稱和說明字串。

針對每個物件或計數器，以及每個支援的語言，您必須提供名稱索引鍵 (包含物件或計數器) 的名稱或標題字串，而且您可以選擇性地提供 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 (檔案中所定義的名稱和說明字串，請從包含.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登錄值。如果對應的語言子機碼不存在，則不會複製該語言的字串。公用程式也會更新 Last Counter 和 Last 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

共用方式為