Adição de nomes e descrições de contadores ao Registro

  • Artigo

Importante

Devido a limitações significativas de desempenho e confiabilidade, o método para fornecer dados de contador de desempenho que este tópico descreve pode ser alterado ou indisponível no futuro. Em vez disso, a Microsoft recomenda que você use o método descrito em Fornecendo dados de contador usando a versão 2.0 para criar novos contadores de desempenho e que você migre contadores de desempenho existentes para usar esse método.

Os nomes e descrições de todos os objetos de desempenho V1 e seus contadores devem ser instalados no sistema. Para armazenar nomes e descrições para os objetos e contadores do seu provedor V1:

Criando um arquivo de constantes simbólicas (.h)

Crie um arquivo de cabeçalho .h que define constantes (macros) para os deslocamentos para os objetos e contadores fornecidos pelo provedor. O cabeçalho .h é usado como entrada para lodctr durante a instalação do provedor e também pode ser usado pelo código C/C++ do seu provedor.

Os valores constantes devem ser consecutivos, até mesmo números começando com zero. Agrupe as constantes por objetos (ou seja, inicie cada grupo com o deslocamento do objeto e siga com os deslocamentos dos contadores para esse objeto).

As constantes no cabeçalho determinam a ordem na qual os contadores são adicionados ao nome e o texto de ajuda no registro. O provedor usa os deslocamentos para determinar qual objeto está sendo consultado e os valores de índice a serem usados ao retornar os dados. Para obter detalhes, consulte Implementando OpenPerformanceData.

O exemplo a seguir mostra um exemplo de um arquivo de constante simbólico, chamado CounterOffsets.h, que é usado no exemplo criando uma DLL de extensão de desempenho .

#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

Criando um arquivo de inicialização (.INI)

O arquivo de inicialização (.INI) contém o nome e as cadeias de caracteres de ajuda para cada objeto e contador definidos no arquivo de símbolo. O arquivo .INI é usado como entrada para lodctr durante a instalação do provedor.

O arquivo .INI deve ser codificado como UTF-16LE (com marca de ordem de byte) e deve ter as seguintes seções e chaves:

[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

Seção [info]

A [info] seção contém informações gerais sobre o provedor. As chaves de seção são definidas da seguinte maneira:

Chave Descrição
Drivername Especifique o nome da chave de desempenho do provedor localizada no Registro sob a HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services chave . Para obter informações sobre como criar essa chave, consulte Criando a chave de desempenho do aplicativo.
SymbolFile Especifique o arquivo de cabeçalho .h que contém valores simbólicos dos objetos e contadores do provedor. Durante a instalação (ao invocar lodctr), o arquivo de cabeçalho deve estar no mesmo diretório que o arquivo .INI.
Confiável Se você incluir essa chave na seção , o [info]lodctr adicionará um valor do Registro de Código de Validação de Biblioteca à sua chave de desempenho com uma assinatura binária da DLL de desempenho. Quando PERFLIB chama sua DLL, ele compara a assinatura com sua DLL para determinar se a DLL foi modificada. O valor da chave confiável é ignorado.

As DriverName chaves e SymbolFile são necessárias.

Seção [objetos]

A [objects] seção fornece uma lista dos objetos de desempenho aos quais o provedor dá suporte. Isso é usado para determinar se cada símbolo da seção se refere a [text] um objeto ou contador.

Para cada objeto (counterset) compatível com seu provedor, adicione uma chave chamada <symbol>_<langid>_NAME= à [objects] seção , em <symbol> que é o nome do objeto e <langid> é a ID do idioma de um dos idiomas com suporte. O valor é ignorado.

Importante

A [objects] seção melhora o desempenho do sistema. Embora a seção de objetos seja opcional, você sempre deve incluir esta seção no arquivo .INI. Se você incluir esta seção, sua DLL de desempenho será chamada somente se você der suporte ao objeto solicitado. Se você não incluir a seção de objetos, sua DLL será chamada para cada consulta porque o sistema não sabe quais objetos seu provedor dá suporte. Se a seção do objeto não estiver incluída, o lodctr gerará uma mensagem no log de eventos do aplicativo informando que o arquivo .INI não continha uma seção de objetos. O identificador de evento dessa mensagem é 2000.

Seção [idiomas]

A [languages] seção fornece uma lista dos identificadores de idioma de cada idioma para o qual o provedor fornece o nome e as cadeias de caracteres de ajuda. Todos os provedores devem dar suporte 009 a (inglês).

Para cada idioma com suporte, adicione uma chave chamada <langid>=. O valor é ignorado, mas para fins de documentação, o valor normalmente é definido como o nome do idioma correspondente, por exemplo, 009=English.

Para a maioria dos idiomas, você deve usar o identificador de idioma principal. A lista completa de identificadores de idioma está no arquivo de cabeçalho Winnt.h, sob o título "IDs de idioma primário". Converta o valor encontrado em Winnt.h em uma sequência de três dígitos hexadecimais removendo o 0x prefixo e adicionando dígitos à esquerda 0 até que a sequência tenha três dígitos de comprimento. Por exemplo, para especificar cadeias de caracteres em inglês (0x9), use 009. Para especificar cadeias de caracteres italianas (0x10), use 010.

Os idiomas chinês e português exigem os identificadores primários e de sublanguagem. Use 404, 804, 416 ou 816 em vez de 004 ou 016.

Seção [text]

A [text] seção fornece o nome e as cadeias de caracteres de ajuda para seus objetos e contadores.

Para cada objeto ou contador e para cada idioma com suporte, você deve fornecer uma chave NAME (contendo o nome ou a cadeia de caracteres de título para seu objeto ou contador) e, opcionalmente, fornecer uma chave HELP (contendo a descrição ou a cadeia de caracteres de explicação para seu objeto ou contador). As chaves devem ser nomeadas <symbol>_<langid>_NAME e <symbol>_<langid>_HELP, em que <symbol> é a constante simbólica para o objeto ou contador (conforme definido no arquivo .h de constante simbólica) e <langid> é o identificador de idioma usado para essa cadeia de caracteres.

Por exemplo, as cadeias de caracteres em inglês para um contador com símbolo MY_COUNTER seriam especificadas como:

MY_COUNTER_009_NAME=My Counter
MY_COUNTER_009_HELP=Description for My Counter.

As teclas de texto podem aparecer em qualquer ordem. As cadeias de caracteres de texto não devem conter caracteres de formatação, como guias.

Exemplo de arquivo INI

Veja a seguir um exemplo de um arquivo de inicialização usado no exemplo Criando uma DLL de extensão de desempenho .

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

Executando a ferramenta Lodctr

Para carregar os nomes e as cadeias de caracteres de ajuda definidas no arquivo de .INI (durante a instalação do provedor), execute a ferramenta lodctr na pasta que contém o arquivo .INI e o arquivo de cabeçalho. A ferramenta está incluída no computador. Você deve executar o lodctr com privilégios elevados. O parâmetro para lodctr é o caminho para o arquivo .INI. Por exemplo, lodctr "C:\Program Files\MyCompany\MyProvider\MyProvider.ini".

Para descarregar os nomes e as cadeias de caracteres de ajuda (durante a desinstalação), execute a ferramenta unlodctr . Você deve executar unlodctr com privilégios elevados. O parâmetro para desalocar é o DriverName do seu provedor (o nome da chave de desempenho do provedor). Por exemplo, unlodctr "MyProvider".

Antes de executar o lodctr, verifique se o aplicativo tem uma entrada na chave Serviços . Para obter detalhes, consulte Criando a chave de desempenho do aplicativo. Se a chave não existir, o lodctr não atualizará o registro com seus nomes e descrições.

Como alternativa à execução do lodctr, você pode chamar LoadPerfCounterTextStrings (definido em Loadperf.h) do programa de instalação para carregar as descrições dos nomes dos contadores. Em seguida, você pode chamar UnloadPerfCounterTextStrings durante a desinstalação .

O utilitário lodctr copia as cadeias de caracteres do arquivo .INI para os valores contadores e ajuda do registro nas subchaves de idioma apropriadas. Se a subchave de idioma correspondente não existir, as cadeias de caracteres para esse idioma não serão copiadas. O utilitário também atualiza o valor do Último Contador e da Última Ajuda . Os nomes e descrições do contador de desempenho são armazenados no local a seguir no 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 = ...

Além de adicionar valores sob a chave PerfLib , a ferramenta lodctr também adiciona os valores a seguir ao nó Serviços do aplicativo. Na maioria dos casos, o aplicativo e o provedor terão uma relação um-para-um; no entanto, é possível que um provedor forneça dados de contador para vários aplicativos, razão pela qual a chave é baseada no aplicativo e não no provedor.

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