Adición de nombres y descripciones de contadores al registro

Importante

Debido a limitaciones significativas de rendimiento y confiabilidad, el método para proporcionar datos de contador de rendimiento que se describen en este tema puede modificarse o no estar disponible en el futuro. En su lugar, Microsoft recomienda usar el método descrito en Proporcionar datos de contador con la versión 2.0 para crear nuevos contadores de rendimiento y migrar los contadores de rendimiento existentes para usar ese método.

Los nombres y descripciones de todos los objetos de rendimiento V1 y sus contadores deben instalarse en el sistema. Para almacenar nombres y descripciones de los objetos y contadores del proveedor V1:

• Cree un archivo de encabezado .h que contenga las constantes simbólicas para los desplazamientos a los objetos y contadores.
• Cree un archivo de inicialización (.INI) que contenga las cadenas.
• Al instalar el componente, ejecute la herramienta lodctr para instalar los nombres y descripciones en el registro.
• Al desinstalar el componente, ejecute la herramienta unlodctr para quitar los nombres y descripciones del registro.

Creación de un archivo de constantes simbólicas (.h)

Cree un archivo de encabezado .h que defina constantes (macros) para los desplazamientos a los objetos y contadores que proporciona el proveedor. El encabezado .h se usa como entrada para lodctr durante la instalación del proveedor y también puede ser utilizado por el código de C/C++ del proveedor.

Los valores constantes deben ser números pares consecutivos que comienzan por cero. Agrupe las constantes por objetos (es decir, inicie cada grupo con el desplazamiento del objeto y, a continuación, siga con los desplazamientos de los contadores para ese objeto).

Las constantes del encabezado determinan el orden en que se agregan los contadores al nombre y el texto de ayuda en el registro. El proveedor usa los desplazamientos para determinar qué objeto se consulta y los valores de índice que se van a usar al devolver los datos. Para obtener más información, consulte Implementación de OpenPerformanceData.

A continuación se muestra un ejemplo de un archivo de constante simbólica, denominado CounterOffsets.h, que se usa en el ejemplo de DLL de creación de una extensión de rendimiento .

#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

Creación de un archivo de inicialización (.INI)

El archivo de inicialización (.INI) contiene el nombre y las cadenas de ayuda de cada objeto y contador definidos en el archivo de símbolos. El archivo .INI se usa como entrada para lodctr durante la instalación del proveedor.

El archivo .INI debe codificarse como UTF-16LE (con marca de orden de bytes) y debe tener las secciones y claves siguientes:

[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] sección

La [info] sección contiene información general sobre el proveedor. Las claves de sección se definen de la siguiente manera:

Clave	Descripción
DriverName	Especifique el nombre de la clave de rendimiento del proveedor ubicada en el Registro bajo la HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services clave. Para obtener información sobre cómo crear esta clave, consulte Creación de la clave de rendimiento de la aplicación.
SymbolFile	Especifique el archivo de encabezado .h que contiene valores simbólicos de los objetos y contadores del proveedor. Durante la instalación (al invocar lodctr), el archivo de encabezado debe estar en el mismo directorio que el archivo .INI.
Confianza	Si incluye esta clave en la [info] sección , lodctr agregará un valor del Registro de código de validación de biblioteca a la clave de rendimiento con una firma binaria del archivo DLL de rendimiento. Cuando PERFLIB llama al archivo DLL, compara la firma con el archivo DLL para determinar si se ha modificado el archivo DLL. Se omite el valor de la clave de confianza .

Las DriverName claves y SymbolFile son necesarias.

Sección [objects]

En la sección se [objects] proporciona una lista de los objetos de rendimiento que admite el proveedor. Se usa para determinar si cada símbolo de la [text] sección hace referencia a un objeto o un contador.

Para cada objeto (conjunto de contadores) admitido por el proveedor, agregue una clave denominada <symbol>_<langid>_NAME= a la [objects] sección , donde <symbol> es el nombre del objeto y <langid> es el identificador de idioma de uno de los idiomas admitidos. El valor se omite.

Importante

La [objects] sección mejora el rendimiento del sistema. Aunque la sección de objetos es opcional, siempre debe incluir esta sección en el archivo .INI. Si incluye esta sección, solo se llama al archivo DLL de rendimiento si admite el objeto solicitado. Si no incluye la sección de objetos, se llama al archivo DLL para cada consulta porque el sistema no sabe qué objetos admite el proveedor. Si no se incluye la sección de objetos, lodctr genera un mensaje en el registro de eventos de la aplicación que indica que el archivo .INI no contenía una sección de objetos. El identificador de evento de este mensaje es 2000.

Sección [idiomas]

En la sección se [languages] proporciona una lista de los identificadores de idioma de cada idioma para el que el proveedor proporciona el nombre y las cadenas de ayuda. Todos los proveedores deben admitir 009 (inglés).

Para cada idioma admitido, agregue una clave denominada <langid>=. El valor se omite, pero para fines de documentación, el valor se establece normalmente en el nombre del idioma correspondiente, por ejemplo 009=English, .

Para la mayoría de los idiomas, debe usar el identificador de idioma principal. La lista completa de identificadores de idioma está en el archivo de encabezado Winnt.h, bajo el encabezado "Identificadores de idioma principal". Convierta el valor encontrado en Winnt.h en una secuencia de 3 dígitos hexadecimales quitando el 0x prefijo y agregando dígitos iniciales 0 hasta que la secuencia tenga 3 dígitos de longitud. Por ejemplo, para especificar cadenas en inglés (0x9), use 009. Para especificar cadenas italianas (0x10), use 010.

Los idiomas chinos y portugueses requieren los identificadores principales y sublanguajes. Use 404, 804, 416 o 816 en lugar de 004 o 016.

Sección [text]

La [text] sección proporciona el nombre y las cadenas de ayuda para los objetos y contadores.

Para cada objeto o contador, y para cada idioma admitido, debe proporcionar una clave NAME (que contenga el nombre o la cadena de título para el objeto o contador) y, opcionalmente, puede proporcionar una clave HELP (que contenga la descripción o la cadena de explicación para el objeto o contador). Las claves se deben denominar <symbol>_<langid>_NAME y , donde <symbol> es la constante simbólica del objeto o contador (tal como se define en el archivo .h de la constante simbólica) y <langid> es el identificador de idioma que se usa <symbol>_<langid>_HELPpara esta cadena.

Por ejemplo, las cadenas en inglés de un contador con símbolo MY_COUNTER se especificarían como:

MY_COUNTER_009_NAME=My Counter
MY_COUNTER_009_HELP=Description for My Counter.

Las claves de texto pueden aparecer en cualquier orden. Las cadenas de texto no deben contener caracteres de formato como tabulaciones.

Archivo INI de ejemplo

A continuación se muestra un ejemplo de un archivo de inicialización que se usa en el ejemplo de DLL de creación de una extensión de rendimiento .

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

Ejecución de la herramienta Lodctr

Para cargar los nombres y las cadenas de ayuda definidas en el archivo de .INI (durante la instalación del proveedor), ejecute la herramienta lodctr desde la carpeta que contiene el archivo de .INI y el archivo de encabezado. La herramienta se incluye con el equipo. Debe ejecutar lodctr con privilegios elevados. El parámetro para lodctr es la ruta de acceso al archivo .INI. Por ejemplo, lodctr "C:\Program Files\MyCompany\MyProvider\MyProvider.ini".

Para descargar los nombres y las cadenas de ayuda (durante la desinstalación), ejecute la herramienta unlodctr . Debe ejecutar unlodctr con privilegios elevados. El parámetro para unlodctr es driverName del proveedor (el nombre de la clave de rendimiento del proveedor). Por ejemplo, unlodctr "MyProvider".

Antes de ejecutar lodctr, asegúrese de que la aplicación tiene una entrada en la clave de servicios . Para obtener más información, consulte Creación de la clave de rendimiento de la aplicación. Si la clave no existe, lodctr no actualizará el registro con sus nombres y descripciones.

Como alternativa a ejecutar lodctr, puede llamar a LoadPerfCounterTextStrings (definido en Loadperf.h) desde el programa de instalación para cargar las descripciones de los nombres de contadores. A continuación, puede llamar a UnloadPerfCounterTextStrings durante la desinstalación.

La utilidad lodctr copia las cadenas del archivo .INI en los valores del Registro counters y Help en las subclaves de idioma adecuadas. Si la subclave de idioma correspondiente no existe, no se copian las cadenas de ese idioma. La utilidad también actualiza el valor Last Counter y Last Help . Los nombres y descripciones del contador de rendimiento se almacenan en la siguiente ubicación del Registro.

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

Además de agregar valores en la clave PerfLib , la herramienta lodctr también agrega los siguientes valores al nodo Servicios de la aplicación. En la mayoría de los casos, la aplicación y el proveedor tendrán una relación uno a uno; Sin embargo, es posible que un proveedor proporcione datos de contador para varias aplicaciones, por lo que la clave se basa en la aplicación y no en el proveedor.

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