Aggiunta dei nomi e delle descrizioni relative ai contatori al Registro di sistema
Importante
A causa di limitazioni significative di prestazioni e affidabilità, il metodo per fornire i 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 creare nuovi contatori delle prestazioni e di eseguire la migrazione dei contatori delle prestazioni esistenti per usare 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 del provider V1:
- Creare un file header .h che contiene le costanti simboliche per gli offset dei tuoi oggetti e contatori.
- Creare un file di inizializzazione (.INI) che contiene le stringhe.
- Quando si installa il componente, eseguire lo strumento lodctr per installare i nomi e le descrizioni nel Registro di sistema.
- Quando si disinstalla il componente, eseguire lo strumento unlodctr per rimuovere i nomi e le descrizioni dal Registro di sistema.
Creare un file di costanti simboliche (.h)
Creare un file di intestazione .h che definisca 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 tuo 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 in base agli oggetti , ovvero avviare ogni gruppo con l'offset dell'oggetto, quindi seguire gli offset dei contatori per tale oggetto.
Le costanti nell'intestazione determinano l'ordine in cui i contatori vengono aggiunti al nome e al testo di aiuto nel registro. Il provider usa gli offset per determinare quale oggetto viene sottoposto a query e i valori di indice da utilizzare quando restituiscono i dati. Per informazioni dettagliate, vedere Implementazione di OpenPerformanceData.
Di seguito viene illustrato un esempio di file costante simbolico denominato CounterOffsets.h, usato nell'esempio Creating a Performance Extension 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
Creazione di un file di inizializzazione (.INI)
Il file di inizializzazione (.INI) contiene il nome e le stringhe d'aiuto per ogni oggetto e contatore definito nel file di simboli. Il file INI viene usato come input per lodctr durante l'installazione del tuo provider.
Il file INI deve essere codificato come UTF-16LE (con byte order mark) 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 sezione [info] 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 che si trova nel Registro di sistema sotto la chiave HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services. Per informazioni sulla creazione di questa chiave, vedere Creating the Application's Performance Key. |
| SymbolFile | Specificare il file di intestazione .h che contiene i 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. |
| Attendibili | Se includi questa chiave nella sezione [info], lodctr aggiungerà un valore di registro Codice di Convalida della Libreria alla tua chiave delle 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 Trusted di viene ignorato. |
Sono necessarie le chiavi DriverName e SymbolFile.
sezione [oggetti]
La sezione [objects] fornisce un elenco degli oggetti prestazioni supportati dal provider. Viene utilizzato per determinare se ogni simbolo della sezione [text] fa riferimento a un oggetto o a un contatore.
Per ogni oggetto (counterset) supportato dal provider, aggiungere una chiave denominata <symbol>_<langid>_NAME= alla sezione [objects], dove <symbol> è il nome dell'oggetto e <langid> è l'ID lingua di una delle lingue supportate. Il valore viene ignorato.
Importante
La sezione [objects] migliora le prestazioni del sistema. Anche se la sezione oggetti è facoltativa, è consigliabile includere sempre questa sezione in . File INI. Se includi questa sezione, la DLL delle prestazioni di sistema viene chiamata solo se supporti 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 degli oggetti. L'identificatore dell'evento di questo messaggio è 2000.
Sezione [languages]
La sezione [languages] 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 a scopo di documentazione il valore viene in genere impostato sul nome della lingua corrispondente, ad esempio 009=English.
Per la maggior parte delle lingue, è consigliabile usare l'identificatore di lingua principale. L'elenco completo degli identificatori di 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 prefisso 0x e aggiungendo cifre 0 iniziali fino a quando la sequenza non è lunga 3 cifre. Ad esempio, per specificare stringhe in inglese (0x9), usare 009. Per specificare le stringhe italiane (0x10), usare 010.
Le lingue cinesi e portoghese richiedono sia gli identificatori primari che secondari. Usare 404, 804, 416 o 816 anziché 004 o 016.
[text] sezione
La sezione [text] fornisce il nome e le stringhe di aiuto 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 facoltativamente specificare 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 <symbol>_<langid>_HELP, dove <symbol> è la costante simbolica per l'oggetto o il contatore (come definito nel file H costante simbolica) e <langid> è l'identificatore di lingua usato per questa stringa.
Ad esempio, le stringhe in inglese 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 tabulazioni.
File INI di esempio
Di seguito è riportato un esempio di file di inizializzazione usato nell'esempio Creazione di una DLL dell'estensione per le 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 definite nel file .INI (durante l'installazione del provider), eseguire lo strumento lodctr dalla cartella che contiene il file .INI e il file header. Lo strumento è incluso nel computer. È necessario eseguire lodctr con privilegi elevati. Il parametro per lodctr è il percorso del tuo file .INI. Ad esempio, lodctr "C:\Program Files\MyCompany\MyProvider\MyProvider.ini".
Per rimuovere i nomi e le stringhe della Guida (durante la disinstallazione), eseguire lo strumento unlodctr. È necessario eseguire unlodctr con privilegi elevati. Il parametro a unlodctr è il DriverName del provider (il nome della chiave delle prestazioni del provider). Ad esempio, unlodctr "MyProvider".
Prima di eseguire lodctr, assicurarsi che la tua applicazione disponga di una voce sotto la chiave Services. Per informazioni dettagliate, vedere Creazione della chiave di prestazione dell'applicazione. Se la chiave non esiste, lodctr non aggiornerà il Registro di sistema con i tuoi nomi e 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 nei valori del Registro di sistema Contatori e Guida nelle sottochiavi della lingua appropriate. Se la sottochiave della lingua corrispondente non esiste, le stringhe per tale lingua non vengono copiate. L'utilità aggiorna anche il valore ultimo contatore e il valore ultimo aiuto. 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 ad aggiungere valori sotto la chiave PerfLib, lo strumento lodctr 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 del contatore per più applicazioni, motivo per cui la chiave è basata 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