Ngen.exe (Gerador de Imagem Nativa)

O Gerador de Imagem Nativa (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 computador específico do processador compilado e as instala no cache de imagens nativas no computador local. O runtime pode usar imagens nativas do cache em vez de usar o compilador JIT (just-in-time) para compilar o assembly original.

Observação

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

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

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

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

Alterações no 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 aplicativo.

• Uma nova ação, updaterecria 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 a Tarefa de Imagem Nativa.

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

Observação

Ngen.exe sintaxe para as versões 1.0 e 1.1 do .NET Framework podem ser encontradas na Sintaxe Herdada do Gerador de Imagem Nativa (Ngen.exe).

Essa ferramenta é instalada automaticamente com o Visual Studio. Para executar a ferramenta, use o Prompt de Comando do Desenvolvedor do Visual Studio ou o PowerShell do Desenvolvedor do Visual Studio.

No prompt de comando, digite o seguinte:

Sintaxe

ngen action [options]

ngen /? | /help

Ações

A tabela a seguir mostra a sintaxe de cada action. 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 options opções e a ajuda.

Ação	Description
install[assemblyNameassemblyPath | ] [scenarios] [config] [/queue[:{1||23}]]	Gere imagens nativas para um assembly e suas dependências e instale as imagens no cache de imagem nativa. Se /queue for especificado, a ação será enfileirada para o serviço de imagem nativa. 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 imagem nativa. 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 tem mais suporte.
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 nativa. As atualizações são sempre agendadas na prioridade 3, portanto, são executadas quando o computador está ocioso.
display [assemblyName | assemblyPath]	Exiba o estado das imagens nativas para um assembly e suas dependências. Se nenhum argumento for fornecido, tudo no cache de imagem nativa será exibido.
executeQueuedItems [1|2|3] - ou - eqi [1|2|3]	Execute trabalhos de compilação na fila. Se uma prioridade for especificada, trabalhos de compilação com prioridade maior ou igual serão executados. Se nenhuma prioridade for especificada, todos os trabalhos de compilação na fila serão executados.
queue{pause | | continuestatus}	Pause o serviço de imagem nativa, permita que o serviço em pausa continue ou consulte o status do serviço.

Arguments

Argument	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 ações e uninstall as display ações. Somente um assembly pode ser especificado por Ngen.exe linha de comando.
assemblyPath	O caminho explícito do assembly. 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. Somente um assembly pode ser especificado por Ngen.exe linha de comando.

Níveis de prioridade

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

Cenários

Scenario	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 exigidas pelas opções de cenário especificadas.

Config

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 associar a dependências. Quando um componente compartilhado é carregado em runtime, 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. A /ExeConfig opção fornece Ngen.exe orientação sobre quais dependências seriam carregadas em runtime.
/AppBase: directoryPath	Ao localizar dependências, use o diretório especificado como a base de aplicativos.

Opções

Opção	Description
/nologo	Suprime a exibição da faixa de inicialização da Microsoft.
/silent	Suprime a exibição de mensagens de sucesso.
/verbose	Exiba 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.

Cuidado

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 política cas (segurança de acesso ao código) não é mais avaliada.

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

Ngen.exe gera imagens nativas para o assembly especificado pelo assemblyname argumento para a ação install 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 e YourAssembly.exe ambos estão instalados no cache de imagens nativas e ambos têm referências a OurDependency.dll. Se MyAssembly.exe estiver desinstalado, OurDependency.dll não será desinstalado. Ele 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 de exibição. Consulte Assembly.FullName.

As imagens nativas geradas por Ngen.exe podem ser compartilhadas entre domínios de aplicativo. Isso significa que você pode usar Ngen.exe em cenários de aplicativo que exigem que os 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 instalaçã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.

Observação

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

Nesta seção Comentários:

• Gerando imagens para cenários diferentes

• Determinando quando usar imagens nativas

  • Melhor uso de memória

  • Inicialização de aplicativo mais rápida

  • Resumo das considerações de uso

• Importância dos endereços base do assembly

• Associação rígida

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

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

• Processamento adiado

• Imagens nativas e compilação JIT

  • Imagens inválidas

• Solução de problemas

  • Visualizador de log de associação de assembly

  • O assistente de depuração gerenciado JITCompilationStart

  • Recusar a geração de imagem nativa

Gerando imagens para cenários diferentes

Depois de gerar uma imagem nativa para um assembly, o runtime tenta localizar e usar essa imagem nativa automaticamente sempre 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 runtime procurará uma imagem nativa gerada com as opções ou /Profile as /Debug opções. Se não for possível encontrar uma imagem nativa correspondente, o runtime será revertido para a compilação JIT padrão. A única maneira de depurar imagens nativas é criar uma imagem nativa com a opção /Debug .

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.

Observação

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

Melhor uso de memória

As imagens nativas podem melhorar significativamente o uso de memória quando o código é compartilhado entre processos. 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.

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 salva uma quantidade fixa de memória para cada instância do aplicativo.

Inicialização de aplicativo mais rápida

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

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

Observação

Antes do .NET Framework 3.5 Service Pack 1, você deve colocar componentes compartilhados e de nome forte no cache de assembly global, pois o carregador executa uma 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 obtida 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 sobre aplicativos podem ajudá-lo a decidir se deseja realizar o esforço de avaliar imagens nativas para seu aplicativo:

• As imagens nativas são carregadas mais rapidamente do que o 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 exigem mais espaço em disco rígido do que os assemblies CIL e podem exigir tempo considerável para gerar.

• 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 diferentes aplicativos ou cenários diferentes. Por exemplo, as informações de configuração em dois aplicativos podem resultar em decisões de associação 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 aplicativo deve ser considerada ao determinar se as imagens nativas podem fornecer um benefício de desempenho:

• Se o aplicativo for executado em um ambiente que usa muitos componentes compartilhados, as imagens nativas permitirão que os componentes sejam compartilhados por vários processos.

• Se o aplicativo usar vários domínios de aplicativo, as imagens nativas permitirão que páginas de código sejam compartilhadas entre domínios.

  Observação

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

• Se o 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. Aplicativos pequenos geralmente não se beneficiam.

• Para aplicativos de longa execução, a compilação JIT de runtime tem um desempenho ligeiramente melhor do que as imagens nativas. (A associação dura pode reduzir essa diferença de desempenho até certo ponto.)

Importância dos endereços base do assembly

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 realocação será ainda mais pronunciado se a associação dura for empregada.

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

Observação

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

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

Associação rígida

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

A associação rígida é apropriada para dependências carregadas em todos os cenários críticos de desempenho do aplicativo. Assim como acontece com qualquer aspecto do uso de imagem nativa, medidas de desempenho cuidadosas são a única maneira de determinar se a associação dura melhora o desempenho do aplicativo.

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

Observação

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

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

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

O código a seguir mostra os atributos de um assembly que tem duas dependências. A primeira dependência (Assembly1) é uma candidata apropriada para associaçã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 do arquivo. Nomes de exibição podem ser usados.

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

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

Observação

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

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

Processamento adiado

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. O e update as install ações 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 fornecem algum controle sobre o serviço. Para obter mais informações, consulte o Serviço de Imagem Nativa.

Imagens nativas e compilação JIT

Se Ngen.exe encontrar métodos em um assembly que não possa gerar, ele os excluirá da imagem nativa. Quando o runtime 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 serã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 que você especifica e determinadas configurações em seu computador. Essas configurações incluem o seguinte:

• A versão do .NET Framework.

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

• A identidade exata de todos os assemblies que 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 runtime procura a imagem nativa gerada com opções e configurações que correspondem ao ambiente atual do computador. O runtime será revertido para a compilação JIT de um assembly se ele 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 instaladas.

• A identidade exata do assembly.

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

• A identidade exata de todos os assemblies que o assembly referencia.

  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 do computador para restringir 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 Code Access Security.

Resolução de problemas

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

Visualizador de log de associação de assembly

Para confirmar se as imagens nativas estão sendo usadas pelo aplicativo, você pode usar o Fuslogvw.exe (Visualizador de Log de Associação de Assembly). Selecione Imagens Nativas na caixa Categorias de Log na janela do visualizador de log de associaçã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.

Recusar a geração de imagem nativa

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

No entanto, observe que isso BypassNGenAttribute não é definido como um tipo na Biblioteca de Classes do .NET Framework. Para consumir o atributo em seu código, primeiro você deve 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 Gerador de Imagem Nativa 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 houver um arquivo de configuração para o assembly, Ngen.exe o usará. Além disso, as imagens nativas são geradas para todos os arquivos de .dll 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 com MyAssembly.exe o caminho especificado.

ngen install c:\myfiles\MyAssembly.exe

Ao localizar assemblies e suas dependências, Ngen.exe usa a mesma lógica de investigação 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 investigação do assembly começa neste diretório. Você pode substituir esse comportamento usando a opção /AppBase .

Observação

Essa é uma alteração do comportamento de Ngen.exe nas versões do .NET Framework 1.0 e 1.1, em que a base de aplicativos é definida como o diretório atual.

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

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

Os assemblies instalados dessa forma 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 exemplo anterior.

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

Para criar uma imagem nativa para um assembly no cache de assembly global, use o nome de 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 a 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 Imagens Nativas

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 imagem nativa.

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 imagem nativa que correspondem ao nome MyAssemblyparcial, suas dependências e todas as raízes que têm uma dependência em MyAssembly:

ngen display MyAssembly

Saber quais raízes dependem de um assembly de componente compartilhado é útil para medir 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 executar Ngen.exe 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"

Atualizando imagens

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

ngen update

Atualizar todas as imagens pode ser um processo longo. Você pode enfileirar as atualizações para execução pelo serviço de imagem nativa usando a opção /queue . Para obter mais informações sobre a opção e as /queue prioridades de instalação, consulte o 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 será removido se ele 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

Observação

Desinstalar /debug cenários não desinstala um cenário que inclua ambos /profile e /debug.

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

ngen uninstall "ClientApp, Version=1.0.0.0"

Os comandos a seguir desinstalam todos os cenários para "ClientApp, Version=1.0.0.0, Culture=neutral, PublicKeyToken=3c7ba247adcd2081, processorArchitecture=MSIL", ou apenas o cenário de depuração para esse 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 acontece com a ação install , fornecer uma extensão requer executar Ngen.exe do diretório que contém o assembly ou especificar um caminho completo.

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

Tarefa de 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 com suporte. Ele também permite que os instaladores usem Ngen.exe (Gerador de Imagem Nativa) para criar e atualizar imagens nativas em um momento adiado.

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

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

A tarefa de imagem nativa está disponível no .NET Framework 4.5 e versões posteriores, ao ser 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á qualquer trabalho adiado que seja enfileirado por instaladores de aplicativos, solicitações de atualização de imagem nativa adiadas e qualquer criação automática de imagem. A tarefa conclui itens de trabalho pendentes e, em seguida, é desligada. Se o computador parar de ficar ocioso enquanto a tarefa estiver em execução, a tarefa será interrompida.

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 por meio de qualquer um desses métodos, ela continuará em execução quando o computador não estiver mais ocioso. As imagens criadas manualmente usando NGen.exe são priorizadas para habilitar um comportamento previsível para instaladores de aplicativos.

Serviço de Imagem Nativa

O serviço de imagem nativa é um serviço windows que gera e mantém imagens nativas. O serviço de imagem nativa permite que o desenvolvedor adie a instalação e a 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 por meio de várias reinicializações, se necessário. Várias compilações de imagem podem ser enfileiradas.

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

Observação

No Windows Vista, o nome exibido para o serviço de imagem nativa é "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 é "V2.0.50727_X86 do Serviço de Otimização de Runtime do .NET" ou "V2.0.50727_X64 do Serviço de Otimização de Runtime do .NET".

Iniciando operações adiadas

Antes de iniciar uma instalação ou atualização, é recomendável 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 permite que o serviço retome:

ngen queue continue

Para adiar a geração de imagem nativa ao instalar um novo aplicativo ou ao atualizar um componente compartilhado, use a opção /queue com as ações ou update as install ações. 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 o 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 aguardar o tempo ocioso. Assembly2 também é instalado sem aguardar o tempo ocioso, mas depois que todas as ações de prioridade 1 tiverem sido concluídas. Assembly3 é instalado quando o serviço detecta 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 ocorrerem de forma síncrona usando a ação executeQueuedItems . Se você fornecer a prioridade opcional, essa ação afetará apenas as ações enfileiradas que têm prioridade igual ou inferior. A prioridade padrão é 3, portanto, o seguinte comando Ngen.exe processa todas as ações enfileiradas imediatamente e não retorna até que elas sejam concluídas:

ngen executeQueuedItems

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

Desligamento do serviço

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

Interação do serviço com clientes

No .NET Framework versão 2.0, a única interação com o serviço de imagem nativa é 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 nativa e interagir com o serviço.

Consulte também

• Ferramentas
• Processo de execução gerenciada
• Como o runtime localiza assemblies
• Shells de linha de comando do desenvolvedor