Ngen.exe (Gerador de Imagem Nativa)

O Native Image Generator (Ngen.exe) é uma ferramenta que melhora o desempenho de aplicativos gerenciados. Ngen.exe cria imagens nativas, que são arquivos que contêm código de máquina compilado específico do processador, e as instala no cache de imagens nativo no computador local. O tempo de execução pode usar imagens nativas do cache em vez de usar o compilador just-in-time (JIT) para compilar o assembly original.

Nota

Ngen.exe compila imagens nativas para assemblies destinados somente ao .NET Framework. O gerador de imagem nativo equivalente para o .NET Core é o CrossGen.

Alterações ao Ngen.exe no .NET Framework 4:

• Ngen.exe agora compila assemblies com confiança total e a diretiva CAS (segurança de acesso ao código) não é mais avaliada.

• As imagens nativas geradas com Ngen.exe não podem mais ser carregadas em aplicativos que estão sendo executados em confiança parcial.

Alterações ao Ngen.exe no .NET Framework versão 2.0:

• A instalação de um assembly também instala suas dependências, simplificando a sintaxe de Ngen.exe.

• As imagens nativas agora podem ser compartilhadas entre domínios de aplicativos.

• Uma nova ação, update, recria imagens que foram invalidadas.

• As ações podem ser adiadas para execução por um serviço que usa o tempo ocioso no computador para gerar e instalar imagens.

• Algumas causas de invalidação de imagem foram eliminadas.

No Windows 8, consulte Tarefa de imagem nativa.

Para obter informações adicionais sobre como usar o Ngen.exe e o serviço de imagem nativa, consulte Serviço de imagem nativa.

Nota

Ngen.exe sintaxe para as versões 1.0 e 1.1 do .NET Framework pode ser encontrada em Native Image Generator (Ngen.exe) Legacy Syntax.

Esta ferramenta é instalada automaticamente com o Visual Studio. Para executar a ferramenta, use o Visual Studio Developer Command Prompt ou o Visual Studio Developer PowerShell.

Na linha de comandos, escreva o seguinte:

Sintaxe

ngen action [options]

ngen /? | /help

Ações

A tabela a seguir mostra a sintaxe de cada actionarquivo . Para obter descrições das partes individuais de um action, consulte as tabelas Argumentos, Níveis de prioridade, Cenários e Configuração . A tabela Opções descreve as opções e options a ajuda.

Ação	Descrição
install[assemblyNameassemblyPath | ] [scenarios] [config] [/queue[:{}|1|23]]	Gere imagens nativas para um assembly e suas dependências e instale as imagens no cache de imagens nativo. Se /queue for especificado, a ação será enfileirada para o serviço de imagem nativo. A prioridade padrão é 3. Consulte a tabela Níveis de prioridade .
uninstall [assemblyName | assemblyPath] [scenarios] [config]	Exclua as imagens nativas de um assembly e suas dependências do cache de imagens nativas. Para desinstalar uma única imagem e suas dependências, use os mesmos argumentos de linha de comando que foram usados para instalar a imagem. Nota: A partir do .NET Framework 4, a ação uninstall * não é mais suportada.
update [/queue]	Atualize imagens nativas que se tornaram inválidas. Se /queue for especificado, as atualizações serão enfileiradas para o serviço de imagem nativo. As atualizações são sempre agendadas na prioridade 3, por isso são executadas quando o computador está ocioso.
display [assemblyName | assemblyPath]	Exiba o estado das imagens nativas de um assembly e suas dependências. Se nenhum argumento for fornecido, tudo no cache de imagem nativo será exibido.
executeQueuedItems [1|2|3] -or- eqi [1|2|3]	Execute trabalhos de compilação em fila. Se uma prioridade for especificada, os trabalhos de compilação com prioridade maior ou igual serão executados. Se nenhuma prioridade for especificada, todos os trabalhos de compilação em fila serão executados.
queue{pause | | continuestatus}	Pause o serviço de imagem nativa, permita que o serviço pausado continue ou consulte o status do serviço.

Argumentos

Argumento	Description
assemblyName	O nome de exibição completo do assembly. Por exemplo, "myAssembly, Version=2.0.0.0, Culture=neutral, PublicKeyToken=0038abc9deabfle5". Nota: Você pode fornecer um nome de assembly parcial, como myAssembly, para as display ações e uninstall . Apenas um assembly pode ser especificado por Ngen.exe linha de comando.
assemblyPath	O caminho explícito da assembleia. Você pode especificar um caminho completo ou relativo. Se você especificar um nome de arquivo sem um caminho, o assembly deverá estar localizado no diretório atual. Apenas um assembly pode ser especificado por Ngen.exe linha de comando.

Níveis de prioridade

Prioridade	Description
1	As imagens nativas são geradas e instaladas imediatamente, sem esperar pelo tempo ocioso.
2	As imagens nativas são geradas e instaladas sem esperar pelo tempo ocioso, mas depois de todas as ações de prioridade 1 (e suas dependências) foram concluídas.
3	As imagens nativas são instaladas quando o serviço de imagem nativo deteta que o computador está ocioso. Consulte Serviço de imagem nativa.

Cenários

Cenário	Description
/Debug	Gere imagens nativas que podem ser usadas em um depurador.
/Profile	Gere imagens nativas que podem ser usadas em um criador de perfil.
/NoDependencies	Gere o número mínimo de imagens nativas exigido pelas opções de cenário especificadas.

Configurar

Configuração	Description
/ExeConfig: exePath	Use a configuração do assembly executável especificado. Ngen.exe precisa tomar as mesmas decisões que o carregador ao vincular a dependências. Quando um componente compartilhado é carregado em tempo de execução, usando o Load método, o arquivo de configuração do aplicativo determina as dependências que são carregadas para o componente compartilhado — por exemplo, a versão de uma dependência que é carregada. O /ExeConfig switch fornece Ngen.exe orientação sobre quais dependências seriam carregadas em tempo de execução.
/AppBase: directoryPath	Ao localizar dependências, use o diretório especificado como base do aplicativo.

Opções

Opção	Description
/nologo	Suprima a exibição do banner de inicialização da Microsoft.
/silent	Suprima a exibição de mensagens de sucesso.
/verbose	Exibir informações detalhadas para depuração.
/help, /?	Exibir sintaxe de comando e opções para a versão atual.

Observações

Para executar Ngen.exe, você deve ter privilégios administrativos.

Atenção

Não execute Ngen.exe em assemblies que não são totalmente confiáveis. A partir do .NET Framework 4, Ngen.exe compila assemblies com confiança total e a diretiva CAS (segurança de acesso ao código) não é mais avaliada.

A partir do .NET Framework 4, as imagens nativas geradas com o Ngen.exe não podem mais ser carregadas em aplicativos que estão sendo executados em confiança parcial. Em vez disso, o compilador just-in-time (JIT) é invocado.

Ngen.exe gera imagens nativas para o assembly especificado pelo assemblyname argumento para a install ação e todas as suas dependências. As dependências são determinadas a partir de referências no manifesto do assembly. O único cenário em que você precisa instalar uma dependência separadamente é quando o aplicativo a carrega usando reflexão, por exemplo, chamando o Assembly.Load método.

Importante

Não use o Assembly.LoadFrom método com imagens nativas. Uma imagem carregada com esse método não pode ser usada por outros assemblies no contexto de execução.

Ngen.exe mantém uma contagem de dependências. Por exemplo, suponha MyAssembly.exe que YourAssembly.exe ambos estejam instalados no cache de imagem nativo e ambos tenham referências a OurDependency.dll. Se MyAssembly.exe estiver desinstalado, OurDependency.dll não será desinstalado. Só é removido quando YourAssembly.exe também é desinstalado.

Se você estiver gerando uma imagem nativa para um assembly no cache de assembly global, especifique seu nome para exibição. Consulte Assembly.FullName.

As imagens nativas que Ngen.exe gera podem ser compartilhadas entre domínios de aplicativos. Isso significa que você pode usar Ngen.exe em cenários de aplicativo que exigem que assemblies sejam compartilhados entre domínios de aplicativo. Para especificar a neutralidade do domínio:

• Aplique o LoaderOptimizationAttribute atributo ao seu aplicativo.

• Defina a AppDomainSetup.LoaderOptimization propriedade ao criar informações de configuração para um novo domínio de aplicativo.

Sempre use código neutro de domínio ao carregar o mesmo assembly em vários domínios de aplicativo. Se uma imagem nativa for carregada em um domínio de aplicativo não compartilhado depois de ter sido carregada em um domínio compartilhado, ela não poderá ser usada.

Nota

O código neutro de domínio não pode ser descarregado e o desempenho pode ser um pouco mais lento, particularmente ao acessar membros estáticos.

Nesta secção Observações:

• Geração de imagens para diferentes cenários

• Determinando quando usar imagens nativas

  • Utilização melhorada da memória

  • Inicialização mais rápida do aplicativo

  • Resumo das considerações de uso

• Importância dos endereços de base de montagem

• Encadernação rígida

  • Especificando uma dica de vinculação para uma dependência

  • Especificando uma dica de vinculação padrão para um assembly

• Processamento diferido

• Imagens nativas e compilação JIT

  • Imagens inválidas

• Resolução de problemas

  • Visualizador de log de vinculação de montagem

  • O assistente de depuração gerenciado JITCompilationStart

  • Desativação da geração de imagens nativas

Geração de imagens para diferentes cenários

Depois de gerar uma imagem nativa para um assembly, o tempo de execução tenta localizar e usar automaticamente essa imagem nativa cada vez que executa o assembly. Várias imagens podem ser geradas, dependendo dos cenários de uso.

Por exemplo, se você executar um assembly em um cenário de depuração ou criação de perfil, o tempo de execução procurará uma imagem nativa que foi gerada com as /Debug opções ou /Profile . Se não for possível encontrar uma imagem nativa correspondente, o tempo de execução será revertido para a compilação JIT padrão. A única maneira de depurar imagens nativas é criar uma imagem nativa com a /Debug opção.

A uninstall ação também reconhece cenários, para que você possa desinstalar todos os cenários ou apenas cenários selecionados.

Determinando quando usar imagens nativas

As imagens nativas podem fornecer melhorias de desempenho em duas áreas: melhor uso de memória e tempo de inicialização reduzido.

Nota

O desempenho de imagens nativas depende de vários fatores que dificultam a análise, como padrões de código e acesso a dados, quantas chamadas são feitas entre os limites do módulo e quantas dependências já foram carregadas por outros aplicativos. A única maneira de determinar se as imagens nativas beneficiam seu aplicativo é por meio de medições de desempenho cuidadosas em seus principais cenários de implantação.

Utilização melhorada da memória

As imagens nativas podem melhorar significativamente o uso da memória quando o código é compartilhado entre processos. As imagens nativas são arquivos do Windows PE, portanto, uma única cópia de um arquivo .dll pode ser compartilhada por vários processos; por outro lado, o código nativo produzido pelo compilador JIT é armazenado na memória privada e não pode ser compartilhado.

Os aplicativos executados em serviços de terminal também podem se beneficiar de páginas de código compartilhadas.

Além disso, não carregar o compilador JIT economiza uma quantidade fixa de memória para cada instância do aplicativo.

Inicialização mais rápida do aplicativo

A pré-compilação de assemblies com Ngen.exe pode melhorar o tempo de inicialização de alguns aplicativos. Em geral, os ganhos podem ser obtidos quando os aplicativos compartilham assemblies de componentes porque depois que o primeiro aplicativo foi iniciado, os componentes compartilhados já estão carregados para aplicativos subsequentes. A inicialização a frio, na qual todos os assemblies em um aplicativo devem ser carregados a partir do disco rígido, não se beneficia tanto das imagens nativas porque o tempo de acesso ao disco rígido predomina.

A vinculação rígida pode afetar o tempo de inicialização, porque todas as imagens vinculadas ao assembly principal do aplicativo devem ser carregadas ao mesmo tempo.

Nota

Antes do .NET Framework 3.5 Service Pack 1, você deve colocar componentes compartilhados e de nome forte no cache de assembly global, porque o carregador executa validação extra em assemblies de nome forte que não estão no cache de assembly global, eliminando efetivamente qualquer melhoria no tempo de inicialização obtido usando imagens nativas. As otimizações introduzidas no .NET Framework 3.5 SP1 removeram a validação extra.

Resumo das considerações de uso

As seguintes considerações gerais e considerações de aplicativo podem ajudá-lo a decidir se deve realizar o esforço de avaliar imagens nativas para seu aplicativo:

• As imagens nativas são carregadas mais rapidamente do que a CIL porque eliminam a necessidade de muitas atividades de inicialização, como compilação JIT e verificação de segurança de tipo.

• As imagens nativas exigem um conjunto de trabalho inicial menor porque não há necessidade do compilador JIT.

• As imagens nativas permitem o compartilhamento de código entre processos.

• As imagens nativas requerem mais espaço no disco rígido do que os assemblies CIL e podem exigir um tempo considerável para serem geradas.

• As imagens nativas devem ser mantidas.

  • As imagens precisam ser regeneradas quando o assembly original ou uma de suas dependências é atendido.

  • Um único assembly pode precisar de várias imagens nativas para uso em aplicativos diferentes ou cenários diferentes. Por exemplo, as informações de configuração em dois aplicativos podem resultar em decisões vinculativas diferentes para o mesmo assembly dependente.

  • As imagens nativas devem ser geradas por um administrador; ou seja, de uma conta do Windows no grupo Administradores.

Além dessas considerações gerais, a natureza do seu aplicativo deve ser considerada ao determinar se as imagens nativas podem fornecer um benefício de desempenho:

• Se seu aplicativo é executado em um ambiente que usa muitos componentes compartilhados, as imagens nativas permitem que os componentes sejam compartilhados por vários processos.

• Se seu aplicativo usa vários domínios de aplicativo, as imagens nativas permitem que as páginas de código sejam compartilhadas entre domínios.

  Nota

  No .NET Framework versões 1.0 e 1.1, imagens nativas não podem ser compartilhadas entre domínios de aplicativo. Este não é o caso na versão 2.0 ou posterior.

• Se o seu aplicativo for executado no Terminal Server, as imagens nativas permitirão o compartilhamento de páginas de código.

• Aplicativos grandes geralmente se beneficiam da compilação para imagens nativas. Aplicações pequenas geralmente não se beneficiam.

• Para aplicativos de longa execução, a compilação JIT em tempo de execução tem um desempenho ligeiramente melhor do que as imagens nativas. (A vinculação rígida pode atenuar essa diferença de desempenho até certo ponto.)

Importância dos endereços de base de montagem

Como as imagens nativas são arquivos do Windows PE, elas estão sujeitas aos mesmos problemas de rebasing que outros arquivos executáveis. O custo de desempenho da recolocação é ainda mais pronunciado se for utilizada uma vinculação rígida.

Para definir o endereço base para uma imagem nativa, use a opção apropriada do compilador para definir o endereço base para o assembly. Ngen.exe usa esse endereço base para a imagem nativa.

Nota

As imagens nativas são maiores do que os assemblies gerenciados a partir dos quais foram criadas. Os endereços de base devem ser calculados para permitir esses tamanhos maiores.

Você pode usar uma ferramenta como dumpbin.exe para exibir o endereço base preferido de uma imagem nativa.

Encadernação rígida

A vinculação rígida aumenta a taxa de transferência e reduz o tamanho do conjunto de trabalho para imagens nativas. A desvantagem da vinculação rígida é que todas as imagens que estão vinculadas a um assembly devem ser carregadas quando o assembly é carregado. Isso pode aumentar significativamente o tempo de inicialização de um aplicativo grande.

A vinculação rígida é apropriada para dependências que são carregadas em todos os cenários críticos de desempenho do seu aplicativo. Como em qualquer aspeto do uso de imagem nativa, medições de desempenho cuidadosas são a única maneira de determinar se a vinculação rígida melhora o desempenho do seu aplicativo.

Os DependencyAttribute atributos e DefaultDependencyAttribute permitem que você forneça dicas de vinculação rígidas para Ngen.exe.

Nota

Esses atributos são dicas para Ngen.exe, não comandos. Usá-los não garante vinculação rígida. O significado desses atributos pode mudar em versões futuras.

Especificando uma dica de vinculação para uma dependência

Aplique o DependencyAttribute a um assembly para indicar a probabilidade de que uma dependência especificada seja carregada. LoadHint.Always Indica que a vinculação rígida é apropriada, Default indica que o padrão para a dependência deve ser usado e Sometimes indica que a vinculação rígida não é apropriada.

O código a seguir mostra os atributos para um assembly que tem duas dependências. A primeira dependência (Assembly1) é um candidato apropriado para vinculação rígida, e a segunda (Assembly2) não.

Imports System.Runtime.CompilerServices
<Assembly:DependencyAttribute("Assembly1", LoadHint.Always)>
<Assembly:DependencyAttribute("Assembly2", LoadHint.Sometimes)>

using System.Runtime.CompilerServices;
[assembly:DependencyAttribute("Assembly1", LoadHint.Always)]
[assembly:DependencyAttribute("Assembly2", LoadHint.Sometimes)]

using namespace System::Runtime::CompilerServices;
[assembly:DependencyAttribute("Assembly1", LoadHint.Always)];
[assembly:DependencyAttribute("Assembly2", LoadHint.Sometimes)];

O nome do assembly não inclui a extensão de nome de arquivo. Nomes de exibição podem ser usados.

Especificando uma dica de vinculação padrão para um assembly

As dicas de vinculação padrão são necessárias apenas para assemblies que serão usados imediata e frequentemente por qualquer aplicativo que tenha uma dependência deles. Aplique o com LoadHint.Always a esses assemblies para especificar que a DefaultDependencyAttribute vinculação rígida deve ser usada.

Nota

Não há razão para aplicar DefaultDependencyAttribute a .dll assemblies que não se enquadram nessa categoria, porque aplicar o atributo com qualquer valor diferente tem o mesmo efeito que LoadHint.Always não aplicar o atributo.

A Microsoft usa o para especificar que a DefaultDependencyAttribute vinculação física é o padrão para um número muito pequeno de assemblies no .NET Framework, como mscorlib.dll.

Processamento diferido

A geração de imagens nativas para um aplicativo muito grande pode levar um tempo considerável. Da mesma forma, alterações em um componente compartilhado ou alterações nas configurações do computador podem exigir que muitas imagens nativas sejam atualizadas. As install ações e update têm uma /queue opção que enfileira a operação para execução adiada pelo serviço de imagem nativa. Além disso, Ngen.exe tem queue e executeQueuedItems ações que proporcionam algum controle sobre o serviço. Para obter mais informações, consulte Serviço de imagem nativa.

Imagens nativas e compilação JIT

Se Ngen.exe encontrar quaisquer métodos em um assembly que não possa gerar, ele os excluirá da imagem nativa. Quando o tempo de execução executa esse assembly, ele reverte para a compilação JIT para os métodos que não foram incluídos na imagem nativa.

Além disso, as imagens nativas não são usadas se o assembly tiver sido atualizado ou se a imagem tiver sido invalidada por qualquer motivo.

Imagens inválidas

Quando você usa Ngen.exe para criar uma imagem nativa de um assembly, a saída depende das opções de linha de comando especificadas e de determinadas configurações no computador. Essas configurações incluem o seguinte:

• A versão do .NET Framework.

• A identidade exata do assembly (a recompilação muda a identidade).

• A identidade exata de todos os assemblies aos quais o assembly faz referência (a recompilação altera a identidade).

• Fatores de segurança.

Ngen.exe registra essas informações quando gera uma imagem nativa. Quando você executa um assembly, o tempo de execução procura a imagem nativa gerada com opções e configurações que correspondem ao ambiente atual do computador. O tempo de execução reverte para a compilação JIT de um assembly se não conseguir encontrar uma imagem nativa correspondente. As seguintes alterações nas configurações e no ambiente de um computador fazem com que as imagens nativas se tornem inválidas:

• A versão do .NET Framework.

  Se você aplicar uma atualização ao .NET Framework, todas as imagens nativas que você criou usando Ngen.exe se tornarão inválidas. Por esse motivo, todas as atualizações do .NET Framework executam o Ngen Update comando, para garantir que todas as imagens nativas sejam regeneradas. O .NET Framework cria automaticamente novas imagens nativas para as bibliotecas do .NET Framework que instala.

• A identidade exata da montagem.

  Se você recompilar um assembly, a imagem nativa correspondente do assembly se tornará inválida.

• A identidade exata de todos os assemblies aos quais o assembly faz referência.

  Se você atualizar um assembly gerenciado, todas as imagens nativas que dependem direta ou indiretamente desse assembly se tornarão inválidas e precisarão ser regeneradas. Isso inclui referências comuns e dependências vinculadas. Sempre que uma atualização de software é aplicada, o programa de instalação deve executar um Ngen Update comando para garantir que todas as imagens nativas dependentes sejam regeneradas.

• Fatores de segurança.

  Alterar a política de segurança da máquina para restringir as permissões concedidas anteriormente a um assembly pode fazer com que uma imagem nativa compilada anteriormente para esse assembly se torne inválida.

  Para obter informações detalhadas sobre como o Common Language Runtime administra a segurança de acesso ao código e como usar permissões, consulte Segurança de acesso ao código.

Resolução de Problemas

Os tópicos de solução de problemas a seguir permitem que você veja quais imagens nativas estão sendo usadas e quais não podem ser usadas pelo seu aplicativo, para determinar quando o compilador JIT começa a compilar um método e mostra como desativar a compilação de imagens nativas de métodos especificados.

Visualizador de log de vinculação de montagem

Para confirmar que as imagens nativas estão sendo usadas pelo seu aplicativo, você pode usar o Fuslogvw.exe (Assembly Binding Log Viewer). Selecione Imagens nativas na caixa Categorias de log na janela do visualizador de log de vinculação. Fuslogvw.exe fornece informações sobre por que uma imagem nativa foi rejeitada.

O assistente de depuração gerenciado JITCompilationStart

Você pode usar o assistente de depuração gerenciado jitCompilationStart (MDA) para determinar quando o compilador JIT começa a compilar uma função.

Desativação da geração de imagens nativas

Em alguns casos, NGen.exe pode ter dificuldade em gerar uma imagem nativa para um método específico, ou você pode preferir que o método seja compilado JIT em vez de compilado para uma imagem nativa. Nesse caso, você pode usar o System.Runtime.BypassNGenAttribute atributo para impedir que NGen.exe gere uma imagem nativa para um método específico. O atributo deve ser aplicado individualmente a cada método cujo código você não deseja incluir na imagem nativa. NGen.exe reconhece o atributo e não gera código na imagem nativa para o método correspondente.

Observe, no entanto, que BypassNGenAttribute não é definido como um tipo na biblioteca de classes do .NET Framework. Para consumir o atributo em seu código, você deve primeiro defini-lo da seguinte maneira:

namespace System.Runtime
{
   [AttributeUsage(AttributeTargets.Method |
                   AttributeTargets.Constructor |
                   AttributeTargets.Property)]
   public class BypassNGenAttribute : Attribute
   {
   }
}

Namespace System.Runtime
    <AttributeUsage(AttributeTargets.Method Or
                    AttributeTargets.Constructor Or
                    AttributeTargets.Property)>
    Public Class BypassNGenAttribute : Inherits Attribute
    End Class
End Namespace

Em seguida, você pode aplicar o atributo por método. O exemplo a seguir instrui o Native Image Generator que ele não deve gerar uma imagem nativa para o ExampleClass.ToJITCompile método.

using System;
using System.Runtime;

public class ExampleClass
{
   [BypassNGen]
   public void ToJITCompile()
   {
   }
}

Imports System.Runtime

Public Class ExampleClass
    <BypassNGen>
    Public Sub ToJITCompile()
    End Sub
End Class

Exemplos

O comando a seguir gera uma imagem nativa para ClientApp.exe, localizada no diretório atual e instala a imagem no cache de imagem nativa. Se existir um arquivo de configuração para o assembly, Ngen.exe o usará. Além disso, imagens nativas são geradas para qualquer .dll arquivos que ClientApp.exe fazem referência.

ngen install ClientApp.exe

Uma imagem instalada com Ngen.exe também é chamada de raiz. Uma raiz pode ser um aplicativo ou um componente compartilhado.

O comando a seguir gera uma imagem nativa para MyAssembly.exe com o caminho especificado.

ngen install c:\myfiles\MyAssembly.exe

Ao localizar assemblies e suas dependências, Ngen.exe usa a mesma lógica de sondagem usada pelo common language runtime. Por padrão, o diretório que contém ClientApp.exe é usado como o diretório base do aplicativo e toda a sondagem de assembly começa nesse diretório. Você pode substituir esse comportamento usando a /AppBase opção.

Nota

Esta é uma alteração do comportamento Ngen.exe no .NET Framework versões 1.0 e 1.1, onde a base do aplicativo é definida para o diretório atual.

Um assembly pode ter uma dependência sem uma referência, por exemplo, se ele carrega um arquivo .dll usando o Assembly.Load método. Você pode criar uma imagem nativa para esse arquivo .dll usando informações de configuração para o assembly do aplicativo, com a /ExeConfig opção. O comando a seguir gera uma imagem nativa para MyLib.dll usar as informações de configuração do MyApp.exe.

ngen install c:\myfiles\MyLib.dll /ExeConfig:c:\myapps\MyApp.exe

Os assemblies instalados dessa maneira não são removidos quando o aplicativo é removido.

Para desinstalar uma dependência, use as mesmas opções de linha de comando que foram usadas para instalá-la. O comando a seguir desinstala o MyLib.dll do exemplo anterior.

ngen uninstall c:\myfiles\MyLib.dll /ExeConfig:c:\myapps\MyApp.exe

Para criar uma imagem nativa para um assembly no cache global de assembly, use o nome para exibição do assembly. Por exemplo:

ngen install "ClientApp, Version=1.0.0.0, Culture=neutral,
  PublicKeyToken=3c7ba247adcd2081, processorArchitecture=MSIL"

NGen.exe gera um conjunto separado de imagens para cada cenário instalado. Por exemplo, os comandos a seguir instalam um conjunto completo de imagens nativas para operação normal, outro conjunto completo para depuração e um terceiro para criação de perfil:

ngen install MyApp.exe
ngen install MyApp.exe /debug
ngen install MyApp.exe /profile

Exibindo o cache de imagem nativo

Depois que as imagens nativas são instaladas no cache, elas podem ser exibidas usando Ngen.exe. O comando a seguir exibe todas as imagens nativas no cache de imagens nativas.

ngen display

A display ação lista todos os assemblies raiz primeiro, seguido por uma lista de todas as imagens nativas no computador.

Use o nome simples de um assembly para exibir informações somente para esse assembly. O comando a seguir exibe todas as imagens nativas no cache de imagens nativas que correspondem ao nome MyAssemblyparcial, suas dependências e todas as raízes que dependem de MyAssembly:

ngen display MyAssembly

Saber quais raízes dependem de um conjunto de componentes compartilhados é útil para avaliar o impacto de uma update ação depois que o componente compartilhado é atualizado.

Se você especificar a extensão de arquivo de um assembly, deverá especificar o caminho ou executá Ngen.exe a partir do diretório que contém o assembly:

ngen display c:\myApps\MyAssembly.exe

O comando a seguir exibe todas as imagens nativas no cache de imagens nativas com o nome MyAssembly e a versão 1.0.0.0.

ngen display "myAssembly, version=1.0.0.0"

Atualização de imagens

Normalmente, as imagens são atualizadas após a atualização de um componente compartilhado. Para atualizar todas as imagens nativas que foram alteradas ou cujas dependências foram alteradas, use a update ação sem argumentos.

ngen update

A atualização de todas as imagens pode ser um processo demorado. Você pode enfileirar as atualizações para execução pelo serviço de imagem nativo usando a /queue opção. Para obter mais informações sobre a opção e as prioridades de /queue instalação, consulte Serviço de imagem nativa.

ngen update /queue

Desinstalando imagens

Ngen.exe mantém uma lista de dependências, para que os componentes compartilhados sejam removidos somente quando todos os assemblies que dependem deles tiverem sido removidos. Além disso, um componente compartilhado não é removido se tiver sido instalado como uma raiz.

O comando a seguir desinstala todos os cenários para a raiz ClientApp.exe:

ngen uninstall ClientApp

A uninstall ação pode ser usada para remover cenários específicos. O comando a seguir desinstala todos os cenários de depuração para ClientApp.exe:

ngen uninstall ClientApp /debug

Nota

A desinstalação /debug de cenários não desinstala um cenário que inclua e /profile/debug.

O comando a seguir desinstala todos os cenários de uma versão específica do ClientApp.exe:

ngen uninstall "ClientApp, Version=1.0.0.0"

Os comandos a seguir desinstalam todos os cenários do "ClientApp, Version=1.0.0.0, Culture=neutral, PublicKeyToken=3c7ba247adcd2081, processorArchitecture=MSIL", ou apenas o cenário de depuração desse assembly:

ngen uninstall "ClientApp, Version=1.0.0.0, Culture=neutral,
  PublicKeyToken=3c7ba247adcd2081, processorArchitecture=MSIL"
ngen uninstall "ClientApp, Version=1.0.0.0, Culture=neutral,
  PublicKeyToken=3c7ba247adcd2081, processorArchitecture=MSIL" /debug

Assim como na install ação, fornecer uma extensão requer a execução de Ngen.exe do diretório que contém o assembly ou a especificação de um caminho completo.

Para obter exemplos relacionados ao serviço de imagem nativa, consulte Serviço de imagem nativa.

Tarefa Imagem Nativa

A tarefa de imagem nativa é uma tarefa do Windows que gera e mantém imagens nativas. A tarefa de imagem nativa gera e recupera imagens nativas automaticamente para cenários suportados. Ele também permite que os instaladores usem Ngen.exe (Native Image Generator) para criar e atualizar imagens nativas em um momento adiado.

A tarefa de imagem nativa é registrada uma vez para cada arquitetura de CPU suportada em um computador, para permitir a compilação de aplicativos destinados a cada arquitetura:

Nome da tarefa	Computador de 32 bits	Computador de 64 bits
NET Framework NGEN v4.0.30319	Sim	Sim
NET Framework NGEN v4.0.30319 64	Não	Sim

A tarefa de imagem nativa está disponível no .NET Framework 4.5 e versões posteriores, quando executada no Windows 8 ou posterior. Em versões anteriores do Windows, o .NET Framework usa o Serviço de Imagem Nativa.

Tempo de vida da tarefa

Em geral, o Agendador de Tarefas do Windows inicia a tarefa de imagem nativa todas as noites quando o computador está ocioso. A tarefa verifica se há trabalho adiado enfileirado por instaladores de aplicativos, solicitações de atualização de imagem nativa adiada e criação automática de imagem. A tarefa conclui itens de trabalho pendentes e, em seguida, é encerrada. Se o computador parar de estar inativo enquanto a tarefa está em execução, a tarefa para.

Você também pode iniciar a tarefa de imagem nativa manualmente por meio da interface do usuário do Agendador de Tarefas ou por meio de chamadas manuais para NGen.exe. Se a tarefa for iniciada através de qualquer um destes métodos, continuará a ser executada quando o computador já não estiver inativo. As imagens criadas manualmente usando NGen.exe são priorizadas para permitir um comportamento previsível para instaladores de aplicativos.

Serviço de Imagem Nativa

O serviço de imagem nativa é um serviço do Windows que gera e mantém imagens nativas. O serviço de imagem nativa permite que o desenvolvedor adie a instalação e atualização de imagens nativas para períodos em que o computador está ocioso.

Normalmente, o serviço de imagem nativa é iniciado pelo programa de instalação (instalador) para um aplicativo ou atualização. Para ações de prioridade 3, o serviço é executado durante o tempo ocioso no computador. O serviço salva seu estado e é capaz de continuar através de várias reinicializações, se necessário. Várias compilações de imagens podem ser enfileiradas.

O serviço também interage com o comando Ngen.exe manual. Os comandos manuais têm precedência sobre a atividade em segundo plano.

Nota

No Windows Vista, o nome exibido para o serviço de imagem nativo é "Microsoft.NET Framework NGEN v2.0.50727_X86" ou "Microsoft.NET Framework NGEN v2.0.50727_X64". Em todas as versões anteriores do Microsoft Windows, o nome é ".NET Runtime Optimization Service v2.0.50727_X86" ou ".NET Runtime Optimization Service v2.0.50727_X64".

Lançamento de operações diferidas

Antes de iniciar uma instalação ou atualização, recomenda-se pausar o serviço. Isso garante que o serviço não seja executado enquanto o instalador estiver copiando arquivos ou colocando assemblies no cache de assembly global. A seguinte linha de comando Ngen.exe pausa o serviço:

ngen queue pause

Quando todas as operações adiadas tiverem sido enfileiradas, o comando a seguir permitirá que o serviço seja retomado:

ngen queue continue

Para adiar a geração de imagens nativas ao instalar um novo aplicativo ou ao atualizar um componente compartilhado, use a /queue opção com as install ações ou update . As seguintes linhas de comando Ngen.exe instalam uma imagem nativa para um componente compartilhado e executam uma atualização de todas as raízes que podem ter sido afetadas:

ngen install MyComponent /queue
ngen update /queue

A update ação regenera todas as imagens nativas que foram invalidadas, não apenas aquelas que usam MyComponent.

Se seu aplicativo consistir em muitas raízes, você poderá controlar a prioridade das ações adiadas. Os comandos a seguir enfileiram a instalação de três raízes. Assembly1 é instalado primeiro, sem esperar pelo tempo ocioso. Assembly2 também é instalado sem esperar pelo tempo ocioso, mas depois de todas as ações de prioridade 1 terem sido concluídas. Assembly3 é instalado quando o serviço deteta que o computador está ocioso.

ngen install Assembly1 /queue:1
ngen install Assembly2 /queue:2
ngen install Assembly3 /queue:3

Você pode forçar ações enfileiradas a ocorrer de forma síncrona usando a executeQueuedItems ação. Se você fornecer a prioridade opcional, essa ação afetará apenas as ações enfileiradas que têm prioridade igual ou menor. A prioridade padrão é 3, portanto, o comando Ngen.exe a seguir processa todas as ações enfileiradas imediatamente e não retorna até que elas sejam concluídas:

ngen executeQueuedItems

Os comandos síncronos são executados por Ngen.exe e não usam o serviço de imagem nativo. Você pode executar ações usando Ngen.exe enquanto o serviço de imagem nativo está em execução.

Desligamento do serviço

Depois de ser iniciado pela execução de um comando Ngen.exe que inclui a /queue opção, o serviço é executado em segundo plano até que todas as ações tenham sido concluídas. O serviço salva seu estado para que possa continuar através de várias reinicializações, se necessário. Quando o serviço deteta que não há mais ações na fila, ele redefine seu status para que não seja reiniciado na próxima vez que o computador for inicializado e, em seguida, ele se desliga.

Interação do Serviço com os Clientes

No .NET Framework versão 2.0, a única interação com o serviço de imagem nativo é por meio da ferramenta de linha de comando Ngen.exe. Use a ferramenta de linha de comando em scripts de instalação para enfileirar ações para o serviço de imagem nativo e interagir com o serviço.

Consulte também

• Ferramentas
• Processo de Execução Gerenciado
• Como o tempo de execução localiza assemblies
• Shells de linha de comando do desenvolvedor