Aggiunta di nomi e descrizioni dei contatori al Registro di sistema

  • Articolo

Importante

A causa di limitazioni significative di prestazioni e affidabilità, il metodo per fornire dati del contatore delle prestazioni descritti in questo argomento potrebbe essere modificato o non disponibile in futuro. Microsoft consiglia invece di usare il metodo descritto in Fornire dati contatori usando la versione 2.0 per la creazione di nuovi contatori delle prestazioni e che si esegue la migrazione di contatori delle prestazioni esistenti per l'uso di tale metodo.

I nomi e le descrizioni di tutti gli oggetti prestazioni V1 e i relativi contatori devono essere installati nel sistema. Per archiviare nomi e descrizioni per gli oggetti e i contatori dal provider V1:

Creazione di un file di costanti simboliche (.h)

Creare un file di intestazione con estensione h che definisce costanti (macro) per gli offset agli oggetti e ai contatori forniti dal provider. L'intestazione h viene usata come input per lodctr durante l'installazione del provider e può essere usata anche dal codice C/C++ del provider.

I valori costanti devono essere consecutivi, anche numeri che iniziano con zero. Raggruppare le costanti per oggetti ,ad esempio avviare ogni gruppo con l'offset dell'oggetto, quindi seguire le offset dei contatori per tale oggetto.

Le costanti nell'intestazione determinano l'ordine in cui i contatori vengono aggiunti al nome e al testo della Guida nel Registro di sistema. Il provider usa gli offset per determinare quale oggetto viene sottoposto a query e i valori di indice da usare durante la restituzione dei dati. Per informazioni dettagliate, vedere Implementazione di OpenPerformanceData.

Di seguito viene illustrato un esempio di file costante simbolico, denominato CounterOffsets.h, usato nell'esempio creazione di una DLL dell'estensione delle prestazioni .

#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

Creazione di un file di inizializzazione (.INI)

Il file di inizializzazione (.INI) contiene il nome e le stringhe della Guida per ogni oggetto e contatore definito nel file di simboli. Il file .INI viene usato come input per lodctr durante l'installazione del provider.

Il file .INI deve essere codificato come UTF-16LE (con contrassegno ordine byte) e deve avere le sezioni e le chiavi seguenti:

[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] sezione

La [info] sezione contiene informazioni generali sul provider. Le chiavi di sezione sono definite come segue:

Chiave Descrizione
DriverName Specificare il nome della chiave di prestazioni del provider situata nel Registro di sistema nella HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services chiave. Per informazioni sulla creazione di questa chiave, vedere Creazione della chiave delle prestazioni dell'applicazione.
SymbolFile Specificare il file di intestazione .h che contiene valori simbolici degli oggetti e dei contatori del provider. Durante l'installazione (quando si richiama lodctr), il file di intestazione deve trovarsi nella stessa directory del file .INI.
Trusted Se si include questa chiave nella [info] sezione, lodctr aggiungerà un valore del Registro di sistema del codice di convalida della libreria alla chiave di prestazioni con una firma binaria della DLL delle prestazioni. Quando PERFLIB chiama la DLL, confronta la firma con la DLL per determinare se la DLL è stata modificata. Il valore della chiave attendibile viene ignorato.

Sono necessarie le DriverName chiavi e SymbolFile .

[oggetti] sezione

La [objects] sezione fornisce un elenco degli oggetti prestazioni supportati dal provider. Viene usato per determinare se ogni simbolo della [text] sezione fa riferimento a un oggetto o a un contatore.

Per ogni oggetto (contatore) supportato dal provider, aggiungere una chiave denominata <symbol>_<langid>_NAME= alla [objects] sezione, dove <symbol> è il nome dell'oggetto ed <langid> è l'ID lingua di una delle lingue supportate. Il valore viene ignorato.

Importante

La [objects] sezione migliora le prestazioni del sistema. Anche se la sezione oggetti è facoltativa, è consigliabile includere sempre questa sezione nel file di .INI. Se si include questa sezione, la DLL delle prestazioni viene chiamata solo se si supporta l'oggetto richiesto. Se non si include la sezione oggetti, la DLL viene chiamata per ogni query perché il sistema non conosce gli oggetti supportati dal provider. Se la sezione dell'oggetto non è inclusa, lodctr genera un messaggio nel registro eventi dell'applicazione che indica che il file .INI non contiene una sezione di oggetti. L'identificatore dell'evento di questo messaggio è 2000.

[lingue] sezione

La [languages] sezione fornisce un elenco degli identificatori di lingua di ogni lingua per cui il provider fornisce il nome e le stringhe della Guida. Tutti i provider devono supportare 009 (inglese).

Per ogni lingua supportata, aggiungere una chiave denominata <langid>=. Il valore viene ignorato, ma per motivi di documentazione il valore è in genere impostato sul nome della lingua corrispondente, ad esempio 009=English.

Per la maggior parte delle lingue, è consigliabile usare l'identificatore del linguaggio primario. L'elenco completo degli identificatori della lingua si trova nel file di intestazione Winnt.h, sotto l'intestazione "ID lingua primaria". Convertire il valore trovato in Winnt.h in una sequenza di 3 cifre esadecimali rimuovendo il 0x prefisso e aggiungendo cifre iniziali 0 fino a quando la sequenza non è lunga 3 cifre. Ad esempio, per specificare stringhe inglesi (0x9), usare 009. Per specificare stringhe italiane (0x10), usare 010.

Le lingue cinese e portoghese richiedono sia gli identificatori primari che di sottolanguage. Usare 404, 804, 416 o 816 anziché 004 o 016.

[testo] sezione

La [text] sezione fornisce il nome e le stringhe della Guida per gli oggetti e i contatori.

Per ogni oggetto o contatore e per ogni lingua supportata, è necessario specificare una chiave NAME (contenente il nome o la stringa del titolo per l'oggetto o il contatore) e è possibile specificare facoltativamente una chiave HELP (contenente la descrizione o la stringa di spiegazione per l'oggetto o il contatore). Le chiavi devono essere denominate <symbol>_<langid>_NAME e , dove <symbol> è la costante simbolica per l'oggetto o il contatore (come definito nel file con costante simbolica .h) ed <langid> è l'identificatore della lingua usato <symbol>_<langid>_HELPper questa stringa.

Ad esempio, le stringhe inglesi per un contatore con simbolo MY_COUNTER verranno specificate come:

MY_COUNTER_009_NAME=My Counter
MY_COUNTER_009_HELP=Description for My Counter.

Le chiavi di testo possono essere visualizzate in qualsiasi ordine. Le stringhe di testo non devono contenere caratteri di formattazione, ad esempio schede.

File INI di esempio

Di seguito è riportato un esempio di file di inizializzazione usato nell'esempio Creazione di una DLL dell'estensione delle prestazioni .

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

Esecuzione dello strumento Lodctr

Per caricare i nomi e le stringhe della Guida definiti nel file di .INI (durante l'installazione del provider), eseguire lodctr tool dalla cartella che contiene il file e il file di intestazione .INI. Lo strumento è incluso nel computer. È necessario eseguire lodctr con privilegi elevati. Il parametro per lodctr è il percorso del file .INI. Ad esempio, lodctr "C:\Program Files\MyCompany\MyProvider\MyProvider.ini".

Per scaricare i nomi e le stringhe della Guida (durante la disinstallazione), eseguire lo strumento unlodctr . È necessario eseguire unlodctr con privilegi elevati. Il parametro per unlodctr è DriverName del provider (il nome della chiave di prestazioni del provider). Ad esempio, unlodctr "MyProvider".

Prima di eseguire lodctr, assicurarsi che l'applicazione abbia una voce nella chiave Servizi . Per informazioni dettagliate, vedere Creazione della chiave delle prestazioni dell'applicazione. Se la chiave non esiste, lodctr non aggiornerà il Registro di sistema con i nomi e le descrizioni.

In alternativa all'esecuzione di lodctr, è possibile chiamare LoadPerfCounterTextStrings (definito in Loadperf.h) dal programma di installazione per caricare le descrizioni dei nomi dei contatori. È quindi possibile chiamare UnloadPerfCounterTextStrings durante la disinstallazione.

L'utilità lodctr copia le stringhe dal file .INI ai contatori e ai valori del Registro di sistema della Guida nelle sottochiavi del linguaggio appropriate. Se la sottochiave del linguaggio corrispondente non esiste, le stringhe per tale lingua non vengono copiate. L'utilità aggiorna anche il valore Last Counter e Last Help . I nomi e le descrizioni dei contatori delle prestazioni vengono archiviati nel percorso seguente nel Registro di sistema.

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

Oltre all'aggiunta di valori nella chiave PerfLib , lodctr tool aggiunge anche i valori seguenti al nodo Services per l'applicazione. Nella maggior parte dei casi, l'applicazione e il provider avranno una relazione uno-a-uno; tuttavia, è possibile che un provider fornisca dati contatori per più applicazioni, motivo per cui la chiave si basa sull'applicazione e non sul provider.

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