Partager via

Ajout de noms de compteurs et de descriptions au Registre

  • Article

Important

En raison de limitations significatives en matière de performances et de fiabilité, la méthode de fourniture de données de compteur de performances décrite dans cette rubrique peut être modifiée ou indisponible à l’avenir. Au lieu de cela, Microsoft vous recommande d’utiliser la méthode décrite dans Fourniture de données de compteur à l’aide de la version 2.0 pour créer des compteurs de performances et de migrer les compteurs de performances existants pour utiliser cette méthode.

Les noms et descriptions de tous les objets de performance V1 et de leurs compteurs doivent être installés sur le système. Pour stocker les noms et les descriptions des objets et des compteurs de votre fournisseur V1 :

Création d’un fichier de constantes symboliques (.h)

Créez un fichier d’en-tête .h qui définit des constantes (macros) pour les décalages vers les objets et les compteurs que votre fournisseur fournit. L’en-tête .h est utilisé comme entrée pour lodctr lors de l’installation de votre fournisseur, et peut également être utilisé par le code C/C++ de votre fournisseur.

Les valeurs constantes doivent être consécutives, des nombres pairs commençant par zéro. Regroupez les constantes par objets (c’est-à-dire, commencez chaque groupe avec le décalage de l’objet, puis suivez avec les décalages des compteurs pour cet objet).

Les constantes dans l’en-tête déterminent l’ordre dans lequel les compteurs sont ajoutés au nom et au texte d’aide dans le Registre. Le fournisseur utilise les décalages pour déterminer l’objet interrogé et les valeurs d’index à utiliser lors du retour des données. Pour plus d’informations, consultez Implémentation d’OpenPerformanceData.

Voici un exemple de fichier de constante symbolique, nommé CounterOffsets.h, qui est utilisé dans l’exemple de DLL Création d’une extension de performance .

#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

Création d’un fichier d’initialisation (.INI)

Le fichier d’initialisation (.INI) contient le nom et les chaînes d’aide pour chaque objet et compteur définis dans votre fichier de symboles. Le fichier .INI est utilisé comme entrée pour lodctr lors de l’installation de votre fournisseur.

Le fichier .INI doit être encodé en UTF-16LE (avec la marque d’ordre d’octet) et doit comporter les sections et clés suivantes :

[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

La [info] section contient des informations générales sur le fournisseur. Les clés de section sont définies comme suit :

Clé Description
DriverName Spécifiez le nom de la clé de performance du fournisseur située dans le Registre sous la HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services clé. Pour plus d’informations sur la création de cette clé, consultez Création de la clé de performance de l’application.
SymbolFile Spécifiez le fichier d’en-tête .h qui contient des valeurs symboliques des objets et compteurs de votre fournisseur. Pendant l’installation (lors de l’appel de lodctr), le fichier d’en-tête doit se trouver dans le même répertoire que le fichier .INI.
Confiance Si vous incluez cette clé dans la [info] section, lodctr ajoute une valeur de Registre Code de validation de bibliothèque à votre clé de performance avec une signature binaire de votre DLL de performances. Lorsque PERFLIB appelle votre DLL, il compare la signature à votre DLL pour déterminer si la DLL a été modifiée. La valeur de la clé approuvée est ignorée.

Les DriverName clés et SymbolFile sont requises.

[objects] section

La [objects] section fournit une liste des objets de performances pris en charge par le fournisseur. Cela permet de déterminer si chaque symbole de la [text] section fait référence à un objet ou à un compteur.

Pour chaque objet (contre-ensemble) pris en charge par votre fournisseur, ajoutez une clé nommée <symbol>_<langid>_NAME= à la [objects] section, où <symbol> est le nom de l’objet et <langid> l’ID de langue de l’une des langues prises en charge. La valeur est ignorée.

Important

La [objects] section améliore les performances du système. Bien que la section objets soit facultative, vous devez toujours inclure cette section dans votre fichier .INI. Si vous incluez cette section, votre DLL de performances est appelée uniquement si vous prenez en charge l’objet demandé. Si vous n’incluez pas la section objets, votre DLL est appelée pour chaque requête, car le système ne sait pas quels objets votre fournisseur prend en charge. Si la section objet n’est pas incluse, lodctr génère un message dans le journal des événements de l’application indiquant que le fichier .INI ne contenait pas de section d’objets. L’identificateur d’événement de ce message est 2000.

[langues] section

La [languages] section fournit une liste des identificateurs de langue de chaque langue pour laquelle votre fournisseur fournit des chaînes de nom et d’aide. Tous les fournisseurs doivent prendre en charge 009 (anglais).

Pour chaque langue prise en charge, ajoutez une clé nommée <langid>=. La valeur est ignorée, mais à des fins de documentation, la valeur est normalement définie sur le nom de la langue correspondante, par exemple 009=English.

Pour la plupart des langues, vous devez utiliser l’identificateur de langue principale. La liste complète des identificateurs de langue se trouve dans le fichier d’en-tête Winnt.h, sous le titre « ID de langue principale ». Convertissez la valeur trouvée dans Winnt.h en une séquence de 3 chiffres hexadécimaux en supprimant le 0x préfixe et en ajoutant des chiffres de début 0 jusqu’à ce que la séquence mesure 3 chiffres. Par exemple, pour spécifier des chaînes anglaises (0x9), utilisez 009. Pour spécifier des chaînes italiennes (0x10), utilisez 010.

Les langues chinoise et portugaise nécessitent les identificateurs principal et sous-langage. Utilisez 404, 804, 416 ou 816 au lieu de 004 ou 016.

[text] section

La [text] section fournit le nom et les chaînes d’aide pour vos objets et compteurs.

Pour chaque objet ou compteur, et pour chaque langue prise en charge, vous devez fournir une clé NAME (contenant le nom ou la chaîne de titre de votre objet ou compteur) et vous pouvez éventuellement fournir une clé HELP (contenant la description ou la chaîne d’explication de votre objet ou compteur). Les clés doivent être nommées <symbol>_<langid>_NAME et <symbol>_<langid>_HELP, où <symbol> est la constante symbolique de l’objet ou du compteur (comme défini dans le fichier .h de constante symbolique) et <langid> est l’identificateur de langue utilisé pour cette chaîne.

Par exemple, les chaînes en anglais d’un compteur avec symbole MY_COUNTER sont spécifiées comme suit :

MY_COUNTER_009_NAME=My Counter
MY_COUNTER_009_HELP=Description for My Counter.

Les touches de texte peuvent apparaître dans n’importe quel ordre. Les chaînes de texte ne doivent pas contenir de caractères de mise en forme tels que des tabulations.

Exemple de fichier INI

Voici un exemple de fichier d’initialisation utilisé dans l’exemple de DLL Création d’une extension de performances .

[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.

Exécution de l’outil Lodctr

Pour charger les noms et les chaînes d’aide définis dans votre fichier .INI (lors de l’installation de votre fournisseur), exécutez l’outil lodctr à partir du dossier qui contient votre fichier .INI et le fichier d’en-tête. L’outil est fourni avec l’ordinateur. Vous devez exécuter lodctr avec des privilèges élevés. Le paramètre de lodctr est le chemin d’accès à votre fichier .INI. Par exemple : lodctr "C:\Program Files\MyCompany\MyProvider\MyProvider.ini".

Pour décharger les noms et les chaînes d’aide (lors de la désinstallation), exécutez l’outil unlodctr . Vous devez exécuter unlodctr avec des privilèges élevés. Le paramètre à annuler est DriverName de votre fournisseur (le nom de la clé de performance du fournisseur). Par exemple : unlodctr "MyProvider".

Avant d’exécuter lodctr, assurez-vous que votre application a une entrée sous la clé Services . Pour plus d’informations, consultez Création de la clé de performance de l’application. Si la clé n’existe pas, lodctr ne met pas à jour le registre avec vos noms et descriptions.

En guise d’alternative à l’exécution de lodctr, vous pouvez appeler LoadPerfCounterTextStrings (défini dans Loadperf.h) à partir de votre programme d’installation pour charger les descriptions des noms de vos compteurs. Vous pouvez ensuite appeler UnloadPerfCounterTextStrings pendant la désinstallation.

L’utilitaire lodctr copie les chaînes du fichier .INI dans les valeurs de Registre Counters et Help sous les sous-clés de langue appropriées. Si la sous-clé de langue correspondante n’existe pas, les chaînes de cette langue ne sont pas copiées. L’utilitaire met également à jour les valeurs Last Counter et Last Help . Les noms et descriptions des compteurs de performances sont stockés à l’emplacement suivant dans le Registre.

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 = ...

En plus d’ajouter des valeurs sous la clé PerfLib , l’outil lodctr ajoute également les valeurs suivantes au nœud Services de l’application. Dans la plupart des cas, l’application et le fournisseur auront une relation un-à-un ; Toutefois, il est possible pour un fournisseur de fournir des données de compteur pour plusieurs applications, c’est pourquoi la clé est basée sur l’application et non sur le fournisseur.

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