Configurando um ambiente de criação de perfil

Observação

Houve alterações substanciais na criação de perfil no .NET Framework 4.

Quando um processo gerenciado (aplicativo ou serviço) é iniciado, ele carrega o CLR (Common Language Runtime). Quando o CLR é inicializado, ele avalia as duas variáveis ambientais a seguir para decidir se o processo deve se conectar a um criador de perfil:

• COR_ENABLE_PROFILING: o CLR se conecta a um criador de perfil somente se essa variável de ambiente existir e for definida como 1.

• COR_PROFILER: se a verificação de COR_ENABLE_PROFILING for aprovada, o CLR se conectará ao criador de perfil que tem esse CLSID ou ProgID, que deve ter sido armazenado anteriormente no registro. A variável de ambiente COR_PROFILER é definida como uma cadeia de caracteres, conforme mostrado nos dois exemplos a seguir.

  set COR_PROFILER={32E2F4DA-1BEA-47ea-88F9-C5DAF691C94A}  
  set COR_PROFILER="MyProfiler"  
  

Para criar o perfil de um aplicativo CLR, você deve definir as variáveis de ambiente COR_ENABLE_PROFILING e COR_PROFILER antes de executar o aplicativo. Você também deve verificar se a DLL do criador de perfil está registrada.

Observação

A partir do .NET Framework 4, os criadores de perfil não precisam ser registrados.

Observação

Para usar .NET Framework versões 2.0, 3.0 e 3.5 nas versões .NET Framework 4 e posteriores, você deve definir a variável de ambiente COMPLUS_ProfAPI_ProfilerCompatibilitySetting.

Escopo de variável de ambiente

Como você define as variáveis de ambiente COR_ENABLE_PROFILING e COR_PROFILER determinará seu escopo de influência. É possível definir essas variáveis de uma das seguintes formas:

• Se você definir as variáveis em uma chamada ICorDebug::CreateProcess, elas serão aplicadas somente ao aplicativo que você está executando no momento. (Elas também serão aplicadas a outros aplicativos iniciados por esse aplicativo que herdam o ambiente.)

• Se você definir as variáveis em uma janela do Prompt de Comando, elas serão aplicadas a todos os aplicativos iniciados nessa janela.

• Se você definir as variáveis no nível do usuário, elas serão aplicadas a todos os aplicativos que você começar com Explorador de Arquivos. Uma janela do Prompt de Comando que você abrir depois de definir as variáveis terá essas configurações de ambiente, assim como qualquer aplicativo que você iniciar a partir dessa janela. Para definir variáveis de ambiente no nível do usuário, clique com o botão direito do mouse em Meu Computador, clique em Propriedades, clique na guia Avançado , clique em Variáveis de Ambiente e adicione as variáveis à lista de Variáveis de usuário.

• Se você definir as variáveis no nível do computador, elas serão aplicadas a todos os aplicativos iniciados nesse computador. Uma janela do Prompt de Comando que você abrir nesse computador terá essas configurações de ambiente, assim como qualquer aplicativo que você iniciar a partir dessa janela. Isso significa que todos os processos gerenciados nesse computador começarão com o criador de perfil. Para definir variáveis de ambiente no nível do computador, clique com o botão direito do mouse em Meu Computador, clique em Propriedades, clique na guia Avançado , clique em Variáveis de Ambiente e adicione as variáveis à lista de Variáveis do sistema. Depois, reinicie o computador. Após a reinicialização, as variáveis estarão disponíveis em todo o sistema.

Se você estiver criando uma criação de perfil de um Serviço Windows, deverá reiniciar o computador depois de definir as variáveis de ambiente e registrar a DLL do criador de perfil. Para obter mais informações sobre essas considerações, consulte a seção Criação de perfil de um serviço Windows.

Considerações adicionais

• A classe de criador de perfil implementa as interfaces ICorProfilerCallback e ICorProfilerCallback2. No .NET Framework versão 2.0, um criador de perfil deve implementar ICorProfilerCallback2. Se não implementar, ICorProfilerCallback2 não será carregado.

• Somente um criador de perfil pode criar o perfil de um processo ao mesmo tempo em um determinado ambiente. Você pode registrar dois profilers diferentes em ambientes diferentes, mas cada um deve criar um perfil de processos separados. O criador de perfil deve ser implementado como uma DLL de servidor COM em processo, que é mapeada para o mesmo espaço de endereço que o processo cujo perfil está sendo criado. Isso significa que o criador de perfil é executado em processo. O .NET Framework não dá suporte a nenhum outro tipo de servidor COM. Por exemplo, se um criador de perfil quiser monitorar aplicativos de um computador remoto, ele deverá implementar agentes coletores em cada computador. Esses agentes enviarão resultados em lote e os comunicarão ao computador de coleta de dados central.

• Como o criador de perfil é um objeto COM instanciado em processo, cada aplicativo com perfil terá sua própria cópia do criador de perfil. Portanto, uma única instância do criador de perfil não precisa lidar com dados de vários aplicativos. No entanto, você precisará adicionar lógica ao código de log do criador de perfil para evitar substituições de arquivo de log de outros aplicativos com perfil.

Inicializando o criador de perfil.

Quando ambas as verificações de variável de ambiente são aprovadas, o CLR cria uma instância do criador de perfil de maneira semelhante à função COM CoCreateInstance. O criador de perfil não é carregado por meio de uma chamada direta para CoCreateInstance. Portanto, uma chamada para CoInitialize, que requer a configuração do modelo de threading, é evitada. Em seguida, o CLR chama o método ICorProfilerCallback::Initialize no criador de perfil. A assinatura desse método é como segue.

HRESULT Initialize(IUnknown *pICorProfilerInfoUnk)  

O criador de perfil deve consultar pICorProfilerInfoUnk para um ponteiro de interface ICorProfilerInfo ou ICorProfilerInfo2 e salvá-lo para que ele possa solicitar mais informações posteriormente durante a criação de perfil.

Configuração de notificações de eventos

Em seguida, o criador de perfil chama o método ICorProfilerInfo::SetEventMask para especificar quais categorias de notificações ele está interessado. Por exemplo, se o criador de perfil estiver interessado apenas em notificações de entrada e saída de notificações e coleta de lixo, ele especifica o seguinte.

ICorProfilerInfo* pInfo;  
pICorProfilerInfoUnk->QueryInterface(IID_ICorProfilerInfo, (void**)&pInfo);  
pInfo->SetEventMask(COR_PRF_MONITOR_ENTERLEAVE | COR_PRF_MONITOR_GC)  

Ao definir a máscara de notificações dessa maneira, o criador de perfil pode limitar quais notificações ele recebe. Essa abordagem ajuda o usuário a criar um criador de perfil simples ou de finalidade especial. Ele também reduz o tempo de CPU que seria desperdiçado enviando notificações que o criador de perfil simplesmente ignoraria.

Determinados eventos do criador de perfil são imutáveis. Isso significa que, assim que esses eventos forem definidos no retorno de chamada ICorProfilerCallback::Initialize, eles não poderão ser desativados e novos eventos não poderão ser ativados. As tentativas de alterar um evento imutável resultarão no ICorProfilerInfo::SetEventMask retornar um HRESULT com falha.

Criação de perfil em um serviço Windows

A criação de perfil de um Serviço windows é como criar perfil de um aplicativo de Common Language Runtime. Ambas as operações de criação de perfil são habilitadas por meio de variáveis de ambiente. Como um Serviço Windows é iniciado quando o sistema operacional é iniciado, as variáveis de ambiente discutidas anteriormente neste tópico já devem estar presentes e definidas para os valores necessários antes do início do sistema. Além disso, a DLL de criação de perfil já deve estar registrada no sistema.

Depois de definir as variáveis de ambiente COR_ENABLE_PROFILING e COR_PROFILER e registrar a DLL do criador de perfil, reinicie o computador de destino para que o Serviço Windows possa detectar essas alterações.

Observe que essas alterações habilitarão a criação de perfil em todo o sistema. Para impedir que todos os aplicativos gerenciados executados posteriormente sejam perfilado, exclua as variáveis de ambiente do sistema depois de reiniciar o computador de destino.

Essa técnica também faz com que todos os processos CLR tenham perfis criados. O criador de perfil deve adicionar lógica ao ICorProfilerCallback::Inicializar o retorno de chamada para detectar se o processo atual é de interesse. Se não for, o criador de perfil poderá falhar no retorno de chamada sem executar a inicialização.

Confira também

• Visão geral da criação de perfil