Ngen.exe (Gerador de Imagens Nativas)Ngen.exe (Native Image Generator)

O Gerador de Imagem Nativa (Ngen.exe) é uma ferramenta que melhora o desempenho de aplicativos gerenciados.The Native Image Generator (Ngen.exe) is a tool that improves the performance of managed applications. Ngen.exe cria imagens nativas, que são arquivos que contém o código de máquina específico do processamento compilado e as instala no cache de imagem nativa do computador local.Ngen.exe creates native images, which are files containing compiled processor-specific machine code, and installs them into the native image cache on the local computer. O tempo de execução pode usar imagens nativas do cache em vez de usar o compilador JIT (Just-In-Time) para compilar o assembly original.The runtime can use native images from the cache instead of using the just-in-time (JIT) compiler to compile the original assembly.

Alterações feitas em Ngen.exe no .NET Framework versão 4:Changes to Ngen.exe in the .NET Framework 4:

  • Ngen.exe agora compila assemblies com confiança total, e a política de segurança de acesso de código (CAS) deixa de ser avaliada.Ngen.exe now compiles assemblies with full trust, and code access security (CAS) policy is no longer evaluated.

  • As imagens nativas geradas com Ngen.exe não podem mais ser carregadas em aplicativos em execução com confiança parcial.Native images that are generated with Ngen.exe can no longer be loaded into applications that are running in partial trust.

Alterações feitas em Ngen.exe no .NET Framework versão 2.0:Changes to Ngen.exe in the .NET Framework version 2.0:

  • A instalação de um assembly também instala suas dependências, o que simplifica a sintaxe de Ngen.exe.Installing an assembly also installs its dependencies, simplifying the syntax of Ngen.exe.

  • As imagens nativas agora podem ser compartilhadas entre domínios de aplicativo.Native images can now be shared across application domains.

  • Uma nova ação, update, recria imagens que foram invalidadas.A new action, update, re-creates images that have been invalidated.

  • 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.Actions can be deferred for execution by a service that uses idle time on the computer to generate and install images.

  • Algumas causas da invalidação de imagem são eliminadas.Some causes of image invalidation have been eliminated.

No Windows 8, confira Tarefa de Imagem Nativa.On Windows 8, see Native Image Task.

Para saber mais sobre como usar o Ngen.exe e o serviço de imagem nativa, confira Serviço de imagem nativa.For additional information on using Ngen.exe and the native image service, see Native Image Service.

Observação

A sintaxe de Ngen.exe para as versões 1.0 e 1.1 do .NET Framework pode ser encontrada em Sintaxe herdada do Gerador de Imagens Nativas (Ngen.exe).Ngen.exe syntax for versions 1.0 and 1.1 of the .NET Framework can be found in Native Image Generator (Ngen.exe) Legacy Syntax.

Essa ferramenta é instalada automaticamente com o Visual Studio.This tool is automatically installed with Visual Studio. Para executar a ferramenta, use o Prompt de Comando do Desenvolvedor para Visual Studio (ou o Prompt de Comando do Visual Studio no Windows 7).To run the tool, use the Developer Command Prompt for Visual Studio (or the Visual Studio Command Prompt in Windows 7). Para obter mais informações, consulte Prompts de Comando.For more information, see Command Prompts.

No prompt de comando, digite o seguinte:At the command prompt, type the following:

SintaxeSyntax

ngen action [options]
ngen /? | /help

AçõesActions

A tabela a seguir mostra a sintaxe de cada action.The following table shows the syntax of each action. Para obter descrições das partes individuais de um action, confira as tabelas Argumentos, Níveis de Prioridade, Cenários e Configuração.For descriptions of the individual parts of an action, see the Arguments, Priority Levels, Scenarios, and Config tables. A tabela Opções descreve o options e as opções da ajuda.The Options table describes the options and the help switches.

AçãoAction DESCRIÇÃODescription
install [assemblyName | assemblyPath] [scenarios] [config] [/queue[:{1|2|3}]]install [assemblyName | assemblyPath] [scenarios] [config] [/queue[:{1|2|3}]] Gere imagens nativas para um assembly e suas dependências e instale as imagens no cache de imagem nativa.Generate native images for an assembly and its dependencies and install the images in the native image cache.

Se /queue for especificado, a ação será enfileirada para o serviço de imagem nativa.If /queue is specified, the action is queued for the native image service. A prioridade padrão é 3.The default priority is 3. Confira a tabela Níveis de Prioridade.See the Priority Levels table.
uninstall [assemblyName | assemblyPath] [scenarios] [config]uninstall [assemblyName | assemblyPath] [scenarios] [config] Exclua as imagens nativas de um assembly e suas dependências do cache de imagem nativa.Delete the native images of an assembly and its dependencies from the native image cache.

Para desinstalar uma única imagem e suas dependências, use os mesmos argumentos de linha de comando que foram usados para instalar a imagem.To uninstall a single image and its dependencies, use the same command-line arguments that were used to install the image. Observação: A partir do .NET Framework 4, não há mais suporte para a ação uninstall *.Note: Starting with the .NET Framework 4, the action uninstall * is no longer supported.
update [/queue]update [/queue] Atualize imagens nativas que se tornaram inválidas.Update native images that have become invalid.

Se /queue for especificado, as atualizações serão enfileiradas para o serviço de imagem nativa.If /queue is specified, the updates are queued for the native image service. Como as atualizações estão sempre programadas na prioridade 3, elas são executadas quando o computador está ocioso.Updates are always scheduled at priority 3, so they run when the computer is idle.
display [assemblyName | assemblyPath]display [assemblyName | assemblyPath] Exiba o estado das imagens nativas para um assembly e suas dependências.Display the state of the native images for an assembly and its dependencies.

Se nenhum argumento for fornecido, tudo no cache de imagem nativa será exibido.If no argument is supplied, everything in the native image cache is displayed.
executeQueuedItems [1|2|3]executeQueuedItems [1|2|3]

-ou--or-

eqi [1|2|3]eqi [1|2|3]
Execute o trabalho de compilação enfileirado.Execute queued compilation jobs.

Se uma prioridade for especificada, trabalhos de compilação com prioridade maior ou igual serão executados.If a priority is specified, compilation jobs with greater or equal priority are executed. Se nenhuma prioridade for especificada, todos os trabalhos de compilação enfileirados serão executados.If no priority is specified, all queued compilation jobs are executed.
queue {pause | continue | status}queue {pause | continue | status} Pause o serviço de imagem nativa, deixe o serviço pausado continuar ou consulte o status do serviço.Pause the native image service, allow the paused service to continue, or query the status of the service.

ArgumentsArguments

ArgumentoArgument DESCRIÇÃODescription
assemblyName O nome para exibição completo do assembly.The full display name of the assembly. Por exemplo, "myAssembly, Version=2.0.0.0, Culture=neutral, PublicKeyToken=0038abc9deabfle5".For example, "myAssembly, Version=2.0.0.0, Culture=neutral, PublicKeyToken=0038abc9deabfle5". Observação: É possível fornecer um nome de assembly parcial como, por exemplo, myAssembly para as ações display e uninstall.Note: You can supply a partial assembly name, such as myAssembly, for the display and uninstall actions.

Somente um assembly pode ser especificado por linha de comando de Ngen.exe.Only one assembly can be specified per Ngen.exe command line.
assemblyPath O caminho explícito do assembly.The explicit path of the assembly. É possível especificar um caminho completo ou relativo.You can specify a full or relative path.

Se você especificar um nome de arquivo sem um caminho, o assembly deverá estar localizado no diretório atual.If you specify a file name without a path, the assembly must be located in the current directory.

Somente um assembly pode ser especificado por linha de comando de Ngen.exe.Only one assembly can be specified per Ngen.exe command line.

Níveis de PrioridadePriority Levels

PrioridadePriority DESCRIÇÃODescription
1 As imagens nativas são geradas e instaladas imediatamente, sem aguardar o tempo ocioso.Native images are generated and installed immediately, without waiting for idle time.
2 As imagens nativas são geradas e instaladas sem aguardar o tempo ocioso, mas depois de todas as ações de prioridade 1 (e suas dependências) serem concluídas.Native images are generated and installed without waiting for idle time, but after all priority 1 actions (and their dependencies) have completed.
3 As imagens nativas são instaladas quando o serviço de imagem nativa detecta que o computador está ocioso.Native images are installed when the native image service detects that the computer is idle. Confira Serviço de imagens nativas.See Native Image Service.

CenáriosScenarios

CenárioScenario DESCRIÇÃODescription
/Debug Gere imagens nativas que possam ser usadas em um depurador.Generate native images that can be used under a debugger.
/Profile Gere imagens nativas que possam ser usadas em um criador de perfil.Generate native images that can be used under a profiler.
/NoDependencies Gere o número mínimo de imagens nativas exigidas pelas opções de cenário especificadas.Generate the minimum number of native images required by the specified scenario options.

ConfigConfig

ConfiguraçãoConfiguration DESCRIÇÃODescription
/ExeConfig: exePath/ExeConfig: exePath Use a configuração do assembly executável especificado.Use the configuration of the specified executable assembly.

Ngen.exe precisa tomar as mesmas decisões do carregador durante a associação a dependências.Ngen.exe needs to make the same decisions as the loader when binding to dependencies. Quando um componente compartilhado é carregado no tempo de execução, usando-se o método Load, o arquivo de configuração do aplicativo determina as dependências carregadas para o componente compartilhado — por exemplo, a versão de uma dependência carregada.When a shared component is loaded at run time, using the Load method, the application's configuration file determines the dependencies that are loaded for the shared component — for example, the version of a dependency that is loaded. A opção /ExeConfig dá a Ngen.exe orientações sobre quais dependências seriam carregadas no tempo de execução.The /ExeConfig switch gives Ngen.exe guidance on which dependencies would be loaded at run time.
/AppBase: directoryPath/AppBase: directoryPath Para localizar dependências, use o diretório especificado como a base do aplicativo.When locating dependencies, use the specified directory as the application base.

OpçõesOptions

OpçãoOption DESCRIÇÃODescription
/nologo Suprima a exibição do banner de inicialização da Microsoft.Suppress the Microsoft startup banner display.
/silent Suprima a exibição das mensagens de êxito.Suppress the display of success messages.
/verbose Exiba informações detalhadas da depuração.Display detailed information for debugging. Observação: devido a limitações do sistema operacional, essa opção não exibe tantas informações adicionais no Windows 98 e no Windows Millennium.Note: Due to operating system limitations, this option does not display as much additional information on Windows 98 and Windows Millennium Edition.
/help, /?/help, /? Exiba a sintaxe de comando e as opções da versão atual.Display command syntax and options for the current release.

ComentáriosRemarks

Para executar Ngen.exe, você deve ter privilégios administrativos.To run Ngen.exe, you must have administrative privileges.

Cuidado

Não execute Ngen.exe em assemblies que não sejam totalmente confiáveis.Do not run Ngen.exe on assemblies that are not fully trusted. A partir do .NET Framework 4, o Ngen.exe compila assemblies com confiança total, e a política de segurança de acesso de código (CAS) deixa de ser avaliada.Starting with the .NET Framework 4, Ngen.exe compiles assemblies with full trust, and code access security (CAS) policy is no longer evaluated.

Do .NET Framework 4 em diante, as imagens nativas geradas com Ngen.exe não podem mais ser carregadas em aplicativos em execução com confiança parcial.Starting with the .NET Framework 4, the native images that are generated with Ngen.exe can no longer be loaded into applications that are running in partial trust. Em vez disso, o compilador JIT é invocado.Instead, the just-in-time (JIT) compiler is invoked.

O Ngen.exe gerencia imagens nativas para o assembly especificado pelo argumento assemblyname para a ação install e todas as suas dependências.Ngen.exe generates native images for the assembly specified by the assemblyname argument to the install action and all its dependencies. As dependências são determinadas com base nas referências do manifesto do assembly.Dependencies are determined from references in the assembly manifest. O único cenário no qual você precisa instalar uma dependência separadamente é quando o aplicativo a carrega usando a reflexão, por exemplo, chamando o método Assembly.Load.The only scenario in which you need to install a dependency separately is when the application loads it using reflection, for example by calling the Assembly.Load method.

Importante

Não use o método Assembly.LoadFrom com imagens nativas.Do not use the Assembly.LoadFrom method with native images. Uma imagem carregada com esse método não pode ser usada por outros assemblies no contexto da execução.An image loaded with this method cannot be used by other assemblies in the execution context.

Ngen.exe mantém uma contagem das dependências.Ngen.exe maintains a count on dependencies. Por exemplo, suponhamos que MyAssembly.exe e YourAssembly.exe estejam ambos instalados no cache de imagem nativa, e ambos tenham referências para OurDependency.dll.For example, suppose MyAssembly.exe and YourAssembly.exe are both installed in the native image cache, and both have references to OurDependency.dll. Se MyAssembly.exe for desinstalado, OurDependency.dll não será desinstalado.If MyAssembly.exe is uninstalled, OurDependency.dll is not uninstalled. Ele só é removido quando YourAssembly.exe também é desinstalado.It is only removed when YourAssembly.exe is also uninstalled.

Se você estiver gerando uma imagem nativa para um assembly no cache de assembly global, especifique seu nome para exibição.If you are generating a native image for an assembly in the global assembly cache, specify its display name. Consulte Assembly.FullName.See Assembly.FullName.

As imagens nativas geradas por Ngen.exe podem ser compartilhadas entre domínios de aplicativo.The native images that Ngen.exe generates can be shared across application domains. Isso significa que é possível usar Ngen.exe em cenários de aplicativo que exijam que os assemblies sejam compartilhados entre domínios de aplicativo.This means you can use Ngen.exe in application scenarios that require assemblies to be shared across application domains. Para especificar a neutralidade do domínio:To specify domain neutrality:

Sempre use o código neutro de domínio ao carregar o mesmo assembly em vários domínios de aplicativo.Always use domain-neutral code when loading the same assembly into multiple application domains. 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.If a native image is loaded into a nonshared application domain after having been loaded into a shared domain, it cannot be used.

Observação

O código neutro de domínio não pode ser descarregado, e o desempenho pode ser um pouco mais lento, especialmente durante o acesso a membros estáticos.Domain-neutral code cannot be unloaded, and performance may be slightly slower, particularly when accessing static members.

Nesta seção Observações:In this Remarks section:

Gerar imagens para cenários diferentesGenerating images for different scenarios

Depois que você tiver gerado uma imagem nativa para um assembly, o tempo de execução tenta localizar e usar automaticamente essa imagem nativa sempre que executa o assembly.After you have generated a native image for an assembly, the runtime automatically attempts to locate and use this native image each time it runs the assembly. Várias imagens podem ser geradas, dependendo dos cenários de uso.Multiple images can be generated, depending on usage scenarios.

Por exemplo, se você executar um assembly em um cenário de depuração ou de criação de perfil, o tempo de execução procurará uma imagem nativa gerada com as opções /Debug ou /Profile.For example, if you run an assembly in a debugging or profiling scenario, the runtime looks for a native image that was generated with the /Debug or /Profile options. Caso ele não consiga encontrar uma imagem nativa correspondente, o tempo de execução é revertido para a compilação JIT padrão.If it is unable to find a matching native image, the runtime reverts to standard JIT compilation. A única maneira de depurar imagens nativas é criando uma imagem nativa com a opção /Debug.The only way to debug native images is to create a native image with the /Debug option.

Como a ação uninstall também reconhece cenários, é possível desinstalar todos os cenários ou apenas os cenários selecionados.The uninstall action also recognize scenarios, so you can uninstall all scenarios or only selected scenarios.

Determinar quando usar imagens nativasDetermining when to Use native images

Imagens nativas podem oferecer melhorias de desempenho em duas áreas: melhor uso da memória e tempo de inicialização reduzido.Native images can provide performance improvements in two areas: improved memory use and reduced startup time.

Observação

O desempenho de imagens nativas depende de vários fatores que dificultam a análise como, por exemplo, padrões de acesso ao código e aos dados, quantas chamadas são feitas entre os limites do módulo e quantas dependências já foram carregadas por outros aplicativos.Performance of native images depends on a number of factors that make analysis difficult, such as code and data access patterns, how many calls are made across module boundaries, and how many dependencies have already been loaded by other applications. A única maneira de determinar se as imagens nativas beneficiam o aplicativo é por meio de medidas de desempenho cuidadosas nos principais cenários de implantação.The only way to determine whether native images benefit your application is by careful performance measurements in your key deployment scenarios.

Uso de memória aprimoradoImproved memory use

Imagens nativas podem melhorar significativamente o uso da memória quando o código é compartilhado entre processos.Native images can significantly improve memory use when code is shared between processes. Como imagens nativas são arquivos do Windows PE, 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 em memória privada e não pode ser compartilhada.Native images are Windows PE files, so a single copy of a .dll file can be shared by multiple processes; by contrast, native code produced by the JIT compiler is stored in private memory and cannot be shared.

Aplicativos executados em serviços de terminal também podem aproveitar páginas de código compartilhadas.Applications that are run under terminal services can also benefit from shared code pages.

Além disso, o não carregamento do compilador JIT salva uma quantidade de memória fixa para cada instância do aplicativo.In addition, not loading the JIT compiler saves a fixed amount of memory for each application instance.

Inicialização mais rápida do aplicativoFaster application startup

A pré-compilação de assemblies com Ngen.exe pode melhorar o tempo de inicialização de alguns aplicativos.Precompiling assemblies with Ngen.exe can improve the startup time for some applications. Em geral, os ganhos podem acontecer quando aplicativos compartilham assemblies de componente, porque depois que o primeiro aplicativo foi iniciado os componentes compartilhados já estão carregados para aplicativos subsequentes.In general, gains can be made when applications share component assemblies because after the first application has been started the shared components are already loaded for subsequent applications. A inicialização fria, em que todos os assemblies em um aplicativo devem ser carregados do disco rígido, não beneficia tanto quanto imagens nativas porque o tempo de acesso ao disco rígido predomina.Cold startup, in which all the assemblies in an application must be loaded from the hard disk, does not benefit as much from native images because the hard disk access time predominates.

A associação forçada pode afetar o tempo de inicialização, pois todas as imagens solidamente associadas ao assembly do aplicativo principal devem ser carregadas ao mesmo tempo.Hard binding can affect startup time, because all images that are hard bound to the main application assembly must be loaded at the same time.

Observação

Antes do .NET Framework 3.5 Service Pack 1, você tinha que colocar componentes compartilhados, de nome forte, no cache de assembly global, pois o carregador realiza a validação extra em assemblies de nome forte que não estão no cache de assembly global, o que elimina efetivamente qualquer melhoria no tempo da inicialização obtido usando imagens nativas.Before the .NET Framework 3.5 Service Pack 1, you should put shared, strong-named components in the global assembly cache, because the loader performs extra validation on strong-named assemblies that are not in the global assembly cache, effectively eliminating any improvement in startup time gained by using native images. As otimizações que foram introduzidas no .NET Framework 3.5 SP1 removeram a validação extra.Optimizations that were introduced in the .NET Framework 3.5 SP1 removed the extra validation.

Resumo das considerações de usoSummary of usage considerations

As seguintes considerações gerais e as considerações de aplicativo podem ajudá-lo na decisão de assumir o esforço de avaliação das imagens nativas para o aplicativo:The following general considerations and application considerations may assist you in deciding whether to undertake the effort of evaluating native images for your application:

  • Imagens nativas são carregadas mais rapidamente do que MSIL porque eliminam a necessidade de muitas atividades de inicialização, como a compilação JIT e a verificação da segurança de tipos.Native images load faster than MSIL because they eliminate the need for many startup activities, such as JIT compilation and type-safety verification.

  • As imagens nativas exigem um conjunto de trabalho inicial menor porque não há necessidade do compilador JIT.Native images require a smaller initial working set because there is no need for the JIT compiler.

  • As imagens nativas permitem o compartilhamento de código entre processos.Native images enable code sharing between processes.

  • As imagens nativas exigem mais espaço em disco rígido do que assemblies MSIL e podem exigir um tempo considerável para geração.Native images require more hard disk space than MSIL assemblies and may require considerable time to generate.

  • As imagens nativas devem ser mantidas.Native images must be maintained.

    • As imagens precisam ser regeneradas quando o assembly original ou uma de suas dependências é atendida.Images need to be regenerated when the original assembly or one of its dependencies is serviced.

    • Um único assembly pode precisar de várias imagens nativas que serão usadas em aplicativos diferentes ou em cenários diferentes.A single assembly may need multiple native images for use in different applications or different scenarios. 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.For example, the configuration information in two applications might result in different binding decisions for the same dependent assembly.

    • As imagens nativas devem ser geradas por um administrador; ou seja, com base em uma conta do Windows no grupo Administradores.Native images must be generated by an administrator; that is, from a Windows account in the Administrators group.

Além dessas considerações gerais, a natureza do aplicativo deve ser levada em consideração durante a determinação da possibilidade das imagens nativas podem oferecer um benefício de desempenho:In addition to these general considerations, the nature of your application must be considered when determining whether native images might provide a performance benefit:

  • Se o aplicativo for executado em um ambiente que usa vários componentes compartilhados, as imagens nativas permitirão que os componentes sejam compartilhados por vários processos.If your application runs in an environment that uses many shared components, native images allow the components to be shared by multiple processes.

  • Se o aplicativo usar vários domínios de aplicativo, as imagens nativas permitirão que as páginas de código sejam compartilhadas entre domínios.If your application uses multiple application domains, native images allow code pages to be shared across domains.

    Observação

    No .NET Framework versões 1.0 e 1.1, as imagens nativas não podem ser compartilhadas entre domínios de aplicativo.In the .NET Framework versions 1.0 and 1.1, native images cannot be shared across application domains. Esse pode não ser o caso na versão 2.0 ou posterior.This is not the case in version 2.0 or later.

  • Se o aplicativo for executado no servidor Host da Sessão da Área de Trabalho Remota, as imagens nativas permitirão o compartilhamento das páginas de código.If your application will be run under Terminal Server, native images allow sharing of code pages.

  • Os aplicativos grandes normalmente se beneficiam da compilação para imagens nativas.Large applications generally benefit from compilation to native images. Os aplicativos pequenos normalmente não beneficiam.Small applications generally do not benefit.

  • Para aplicativos executados por muito tempo, a compilação JIT do tempo de execução é um pouco melhor do que a de imagens nativas.For long-running applications, run-time JIT compilation performs slightly better than native images. (A associação forçada pode atenuar essa diferença de desempenho em algum grau.)(Hard binding can mitigate this performance difference to some degree.)

Importância de endereços de base do assemblyImportance of assembly base addresses

Como são arquivos do Windows PE, as imagens nativas estão sujeitas aos mesmos problemas de rebase de outros arquivos executáveis.Because native images are Windows PE files, they are subject to the same rebasing issues as other executable files. O custo de desempenho da realocação ficará ainda mais evidente se a associação forçada não for utilizada.The performance cost of relocation is even more pronounced if hard binding is employed.

Para definir o endereço base para uma imagem nativa, use a opção apropriada do compilador para definir o endereço base do assembly.To set the base address for a native image, use the appropriate option of your compiler to set the base address for the assembly. Ngen.exe usa esse endereço base para a imagem nativa.Ngen.exe uses this base address for the native image.

Observação

As imagens nativas são maiores que os assemblies gerenciados a partir dos quais foram criadas.Native images are larger than the managed assemblies from which they were created. Os endereços de base devem ser calculados para possibilitar tamanhos maiores.Base addresses must be calculated to allow for these larger sizes.

É possível usar uma ferramenta como dumpbin.exe para exibir o endereço de base preferencial de uma imagem nativa.You can use a tool such as dumpbin.exe to view the preferred base address of a native image.

Associação forçadaHard binding

A associação forçada aumenta a taxa de transferência e reduz o tamanho do conjunto de trabalho de imagens nativas.Hard binding increases throughput and reduces working set size for native images. A desvantagem da associação forçada é que todas as imagens associadas forçadamente a um assembly devem ser carregadas quando o assembly é carregado.The disadvantage of hard binding is that all the images that are hard bound to an assembly must be loaded when the assembly is loaded. Isso pode aumentar significativamente o tempo de inicialização de um aplicativo grande.This can significantly increase startup time for a large application.

A associação forçada é apropriada para dependências carregadas em todos os cenários de desempenho crítico do aplicativo.Hard binding is appropriate for dependencies that are loaded in all your application's performance-critical scenarios. Assim como acontece com qualquer aspecto do uso da imagem nativa, medidas de desempenho cuidadosas são a única maneira de determinar se a associação forçada melhora o desempenho do aplicativo.As with any aspect of native image use, careful performance measurements are the only way to determine whether hard binding improves your application's performance.

Os atributos DependencyAttribute e DefaultDependencyAttribute permitem que você dê dicas de associação forçada a Ngen.exe.The DependencyAttribute and DefaultDependencyAttribute attributes allow you to provide hard binding hints to Ngen.exe.

Observação

Esses atributos são dicas para Ngen.exe, e não comandos.These attributes are hints to Ngen.exe, not commands. O uso deles não garante a associação forçada.Using them does not guarantee hard binding. O significado desses atributos pode ser alterado em versões futuras.The meaning of these attributes may change in future releases.

Especificar uma dica de associação para uma dependênciaSpecifying a binding hint for a dependency

Aplique o DependencyAttribute a um assembly para indicar a probabilidade de que uma dependência especificada será carregada.Apply the DependencyAttribute to an assembly to indicate the likelihood that a specified dependency will be loaded. LoadHint.Always indica que a associação forçada é apropriada, Default indica que o padrão da dependência deve ser usado e Sometimes indica que a associação forçada não é apropriada.LoadHint.Always indicates that hard binding is appropriate, Default indicates that the default for the dependency should be used, and Sometimes indicates that hard binding is not appropriate.

O código a seguir mostra os atributos de um assembly que possui duas dependências.The following code shows the attributes for an assembly that has two dependencies. A primeira dependência (Assembly1) é uma candidata apropriada à associação forçada, mas a segunda (Assembly2) não é.The first dependency (Assembly1) is an appropriate candidate for hard binding, and the second (Assembly2) is not.

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 do nome de arquivo.The assembly name does not include the file name extension. Os nomes para exibição podem ser usados.Display names can be used.

Especificar uma dica de associação padrão para um assemblySpecifying a default binding hint for an assembly

As dicas de associação padrão só são necessárias para assemblies que serão usados imediata e frequentemente por qualquer aplicativo que tenha uma dependência neles.Default binding hints are only needed for assemblies that will be used immediately and frequently by any application that has a dependency on them. Aplique o DefaultDependencyAttribute com LoadHint.Always a esses assemblies para especificar que a associação forçada deve ser usada.Apply the DefaultDependencyAttribute with LoadHint.Always to such assemblies to specify that hard binding should be used.

Observação

Não há motivo para aplicar DefaultDependencyAttribute a assemblies .dll que não estejam nessa categoria, porque a aplicação do atributo com qualquer valor diferente de LoadHint.Always tem o mesmo efeito de não aplicar o atributo.There is no reason to apply DefaultDependencyAttribute to .dll assemblies that do not fall into this category, because applying the attribute with any value other than LoadHint.Always has the same effect as not applying the attribute at all.

A Microsoft usa o DefaultDependencyAttribute para especificar que a associação forçada é o padrão para um número muito pequeno de assemblies no .NET Framework como, por exemplo, mscorlib.dll.Microsoft uses the DefaultDependencyAttribute to specify that hard binding is the default for a very small number of assemblies in the .NET Framework, such as mscorlib.dll.

Processamento adiadoDeferred processing

A geração de imagens nativas para um aplicativo muito grande pode demorar um tempo considerável.Generation of native images for a very large application can take considerable time. Da mesma forma, alterações feitas em um componente compartilhado ou alterações feitas em configurações do computador podem exigir a atualização de muitas imagens nativas.Similarly, changes to a shared component or changes to computer settings might require many native images to be updated. As ações install e update têm uma opção /queue que enfileira a operação para execução adiada pelo serviço de imagem nativa.The install and update actions have a /queue option that queues the operation for deferred execution by the native image service. Além disso, Ngen.exe tem ações queue e executeQueuedItems que oferecem certo controle sobre o serviço.In addition, Ngen.exe has queue and executeQueuedItems actions that provide some control over the service. Para saber mais, confira Serviço de imagens nativas.For more information, see Native Image Service.

Imagens nativas e compilação JITNative images and JIT compilation

Se encontrar algum método em um assembly que não puder gerar, Ngen.exe os excluirá da imagem nativa.If Ngen.exe encounters any methods in an assembly that it cannot generate, it excludes them from the native image. Ao executar esse assembly, o tempo de execução o reverte para compilação JIT dos métodos que não foram incluídos na imagem nativa.When the runtime executes this assembly, it reverts to JIT compilation for the methods that were not included in the native image.

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.In addition, native images are not used if the assembly has been upgraded, or if the image has been invalidated for any reason.

Imagens inválidasInvalid images

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 do computador.When you use Ngen.exe to create a native image of an assembly, the output depends upon the command-line options that you specify and certain settings on your computer. Entre essas configurações estão as seguintes:These settings include the following:

  • A versão do .NET Framework.The version of the .NET Framework.

  • A versão do sistema operacional, se a alteração for da família Windows 9x para a família Windows NT.The version of the operating system, if the change is from the Windows 9x family to the Windows NT family.

  • A identidade exata do assembly (recompilação altera a identidade).The exact identity of the assembly (recompilation changes identity).

  • A identidade exata de todos os assemblies aos quais o assembly faz referência (recompilação altera a identidade).The exact identity of all assemblies that the assembly references (recompilation changes identity).

  • Fatores de segurança.Security factors.

Ngen.exe registra essas informações ao gerar uma imagem nativa.Ngen.exe records this information when it generates a native image. Quando você executa um assembly, o tempo de execução procura a imagem nativa gerada com opções e configurações correspondentes ao ambiente atual do computador.When you execute an assembly, the runtime looks for the native image generated with options and settings that match the computer's current environment. O tempo de execução será revertido para a compilação JIT de um assembly se não conseguir encontrar uma imagem nativa correspondente.The runtime reverts to JIT compilation of an assembly if it cannot find a matching native image. As seguintes alterações feitas nas configurações e no ambiente de um computador invalidam imagens nativas:The following changes to a computer's settings and environment cause native images to become invalid:

  • A versão do .NET Framework.The version of the .NET Framework.

    Se você aplicar uma atualização ao .NET Framework, todas as imagens nativas criadas usando-se Ngen.exe serão invalidadas.If you apply an update to the .NET Framework, all native images that you have created using Ngen.exe become invalid. Por esse motivo, todas as atualizações do .NET Framework executam o comando Ngen Update, para garantir que todas as imagens nativas sejam regeneradas.For this reason, all updates of the .NET Framework execute the Ngen Update command, to ensure that all native images are regenerated. O .NET Framework cria automaticamente novas imagens nativas para as bibliotecas do .NET Framework instaladas.The .NET Framework automatically creates new native images for the .NET Framework libraries that it installs.

  • A versão do sistema operacional, se a alteração for da família Windows 9x para a família Windows NT.The version of the operating system, if the change is from the Windows 9x family to the Windows NT family.

    Por exemplo, se a versão do sistema operacional em execução em um computador mudar do Windows 98 para o Windows XP, todas as imagens nativas armazenadas no cache de imagem nativa serão invalidadas.For example, if the version of the operating system running on a computer changes from Windows 98 to Windows XP, all native images stored in the native image cache become invalid. No entanto, se o sistema operacional mudar do Windows 2000 para o Windows XP, as imagens não serão invalidadas.However, if the operating system changes from Windows 2000 to Windows XP, the images are not invalidated.

  • A identidade exata do assembly.The exact identity of the assembly.

    Se você recompilar um assembly, a imagem nativa correspondente do assembly será invalidada.If you recompile an assembly, the assembly's corresponding native image becomes invalid.

  • A identidade exata de todos os assemblies aos quais o assembly faz referência.The exact identity of any assemblies the assembly references.

    Se você atualizar um assembly gerenciado, todas as imagens nativas que dependam direta ou indiretamente desse assembly serão invalidadas e precisarão ser regeneradas.If you update a managed assembly, all native images that directly or indirectly depend on that assembly become invalid and need to be regenerated. Isso inclui as referências comuns e as dependências associadas forçadamente.This includes both ordinary references and hard-bound dependencies. Sempre que uma atualização de software for aplicada, o programa de instalação deverá executar um comando Ngen Update para garantir que as todas as imagens nativas dependentes sejam regeneradas.Whenever a software update is applied, the installation program should execute an Ngen Update command to ensure that all dependent native images are regenerated.

  • Fatores de segurança.Security factors.

    A alteração da política de segurança do computador para restringir permissões concedidas anteriormente a um assembly pode invalidar uma imagem nativa compilada anteriormente para esse assembly.Changing machine security policy to restrict permissions previously granted to an assembly can cause a previously compiled native image for that assembly to become invalid.

    Para obter informações detalhadas sobre como o Common Language Runtime administra a segurança de acesso do código e como usar permissões, confira Segurança de acesso do código.For detailed information about how the common language runtime administers code access security and how to use permissions, see Code Access Security.

Solução de problemasTroubleshooting

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 por seu aplicativo, para determinar quando o compilador JIT começa a compilar um método, e mostra como recusar a compilação de imagem nativa dos métodos especificados.The following troubleshooting topics allow you to see which native images are being used and which cannot be used by your application, to determine when the JIT compiler starts to compile a method, and shows how to opt out of native image compilation of specified methods.

Visualizador de Log de Associação do AssemblyAssembly Binding Log Viewer

Para confirmar que as imagens nativas estão sendo usadas pelo aplicativo, é possível usar Fuslogvw.exe (Visualizador do Log de Associações de Assembly).To confirm that native images are being used by your application, you can use the Fuslogvw.exe (Assembly Binding Log Viewer). Selecione Imagens Nativas na caixa Categorias de Log na janela do visualizador de log da associação.Select Native Images in the Log Categories box on the binding log viewer window. O Fuslogvw.exe fornece informações sobre por que uma imagem nativa foi rejeitada.Fuslogvw.exe provides information about why a native image was rejected.

O assistente de depuração gerenciado JITCompilationStartThe JITCompilationStart managed debugging assistant

É possível usar o MDA (Assistente para depuração gerenciada) jitCompilationStart para determinar quando o compilador JIT começa a compilar uma função.You can use the jitCompilationStart managed debugging assistant (MDA) to determine when the JIT compiler starts to compile a function.

Recusa da geração automática de imagem nativaOpting out of native image generation

Em alguns casos, o NGen.exe pode ter dificuldade para gerar uma imagem nativa para um método específico, ou talvez você prefira que o método seja compilado pelo JIT, em vez de ser compilado para uma imagem nativa.In some cases, NGen.exe may have difficulty generating a native image for a specific method, or you may prefer that the method be JIT compiled rather then compiled to a native image. Nesse caso, você pode usar o atributo System.Runtime.BypassNGenAttribute para impedir que o NGen.exe gere uma imagem nativa para um método específico.In this case, you can use the System.Runtime.BypassNGenAttribute attribute to prevent NGen.exe from generating a native image for a particular method. O atributo deve ser aplicado individualmente a cada método cujo código você não quer incluir na imagem nativa.The attribute must be applied individually to each method whose code you do not want to include in the native image. O NGen.exe reconhece o atributo e não gera um código na imagem nativa para o método correspondente.NGen.exe recognizes the attribute and does not generate code in the native image for the corresponding method.

No entanto, observe que BypassNGenAttribute não está definido como um tipo na Biblioteca de Classes .NET Framework.Note, however, that BypassNGenAttribute is not defined as a type in the .NET Framework Class Library. Para consumir o atributo em seu código, primeiro definia-o da seguinte maneira:In order to consume the attribute in your code, you must first define it as follows:

namespace System.Runtime
{
   public class BypassNGenAttribute : Attribute 
   {
   }   
}
Namespace System.Runtime
   Public Class BypassNGenAttribute : Inherits Attribute 
   End Class   
End Namespace

Depois, você pode aplicar o atributo de acordo com o método.You can then apply the attribute on a per-method basis. O exemplo a seguir instrui o Gerador de imagem nativa que ele não deve gerar uma imagem nativa para o método ExampleClass.ToJITCompile.The following example instructs the Native Image Generator that it should not generate a native image for the ExampleClass.ToJITCompile method.

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

ExemplosExamples

O comando a seguir gera uma imagem nativa para ClientApp.exe, localizado no diretório atual, e instala a imagem no cache de imagem nativa.The following command generates a native image for ClientApp.exe, located in the current directory, and installs the image in the native image cache. Se existir um arquivo de configuração para o assembly, Ngen.exe o usará.If a configuration file exists for the assembly, Ngen.exe uses it. Além de isso, imagens nativas são geradas para todos os arquivos .dll a que ClientApp.exe faz referência.In addition, native images are generated for any .dll files that ClientApp.exe references.

ngen install ClientApp.exe

Uma imagem instalada com Ngen.exe também é chamada de raiz.An image installed with Ngen.exe is also called a root. Uma raiz pode ser um aplicativo ou um componente compartilhado.A root can be an application or a shared component.

O comando a seguir gera uma imagem nativa para MyAssembly.exe com o caminho especificado.The following command generates a native image for MyAssembly.exe with the specified path.

ngen install c:\myfiles\MyAssembly.exe

Para localizar assemblies e as suas dependências, Ngen.exe usa a mesma lógica de investigação usada pelo Common Language Runtime.When locating assemblies and their dependencies, Ngen.exe uses the same probing logic used by the common language runtime. Por padrão, o diretório que contém ClientApp.exe é usado como diretório base do aplicativo, e toda investigação de assembly começa nesse diretório.By default, the directory that contains ClientApp.exe is used as the application base directory, and all assembly probing begins in this directory. É possível substituir esse comportamento usando-se a opção /AppBase.You can override this behavior by using the /AppBase option.

Observação

Essa é uma alteração no comportamento de Ngen.exe no .NET Framework versões 1.0 e 1.1, em que a base do aplicativo é definida como o diretório atual.This is a change from Ngen.exe behavior in the .NET Framework versions 1.0 and 1.1, where the application base is set to the current directory.

Um assembly pode ter uma dependência sem uma referência, por exemplo, se carregar um arquivo .dll usando o método Assembly.Load.An assembly can have a dependency without a reference, for example if it loads a .dll file by using the Assembly.Load method. É possível criar uma imagem nativa para esse arquivo .dll usando-se as informações de configuração do assembly do aplicativo, com a opção /ExeConfig.You can create a native image for such a .dll file by using configuration information for the application assembly, with the /ExeConfig option. O comando a seguir gera uma imagem nativa para MyLib.dll, usando as informações de configuração de MyApp.exe.The following command generates a native image for MyLib.dll, using the configuration information from 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.Assemblies installed in this way are not removed when the application is removed.

Para desinstalar uma dependência, use as mesmas opções de linha de comando que foram usadas para instalá-la.To uninstall a dependency, use the same command-line options that were used to install it. O comando a seguir desinstala o MyLib.dll do exemplo anterior.The following command uninstalls the MyLib.dll from the previous example.

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 para exibição do assembly.To create a native image for an assembly in the global assembly cache, use the display name of the assembly. Por exemplo:For example:

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.NGen.exe generates a separate set of images for each scenario you install. Por exemplo, os seguintes comandos 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:For example, the following commands install a complete set of native images for normal operation, another complete set for debugging, and a third for profiling:

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

Exibindo o Cache de Imagem NativaDisplaying the Native Image Cache

Depois de serem instaladas no cache, as imagens nativas poderão ser exibidas usando-se Ngen.exe.Once native images are installed in the cache, they can be displayed using Ngen.exe. O comando a seguir exibe todas as imagens nativas no cache de imagem nativa.The following command displays all native images in the native image cache.

ngen display

A ação display lista todos os assemblies raiz primeiro, seguido de uma lista de todas as imagens nativas no computador.The display action lists all the root assemblies first, followed by a list of all the native images on the computer.

Use o nome simples de um assembly para exibir informações somente desse assembly.Use the simple name of an assembly to display information only for that assembly. O seguinte comando exibe todas as imagens nativas no cache de imagem nativa que correspondem ao nome parcial MyAssembly, suas dependências e todas as raízes que tenham uma dependência em MyAssembly:The following command displays all native images in the native image cache that match the partial name MyAssembly, their dependencies, and all roots that have a dependency on MyAssembly:

ngen display MyAssembly

Saber quais raízes dependem de um assembly de componente compartilhado é útil na avaliação do impacto de uma ação update depois que o componente compartilhado é atualizado.Knowing what roots depend on a shared component assembly is useful in gauging the impact of an update action after the shared component is upgraded.

Se especificar a extensão de arquivo de um assembly, você deverá especificar o caminho ou executar Ngen.exe no diretório que contém o assembly:If you specify an assembly's file extension, you must either specify the path or execute Ngen.exe from the directory containing the assembly:

ngen display c:\myApps\MyAssembly.exe

O comando a seguir exibe todas as imagens nativas no cache de imagem nativa com o nome MyAssemblye a versão 1.0.0.0.The following command displays all native images in the native image cache with the name MyAssembly and the version 1.0.0.0.

ngen display "myAssembly, version=1.0.0.0"

Atualizando ImagensUpdating Images

As imagens normalmente são atualizadas depois que um componente compartilhado é atualizado.Images are typically updated after a shared component has been upgraded. Para atualizar todas as imagens nativas alteradas, ou cujas dependências foram alteradas, use a ação update sem argumentos.To update all native images that have changed, or whose dependencies have changed, use the update action with no arguments.

ngen update

A atualização de todas as imagens pode ser um processo demorado.Updating all images can be a lengthy process. É possível enfileirar as atualizações para execução pelo serviço de imagem nativa usando-se a opção /queue.You can queue the updates for execution by the native image service by using the /queue option. Para saber mais sobre a opção /queue e as prioridades de instalação, confira Serviço de imagem nativa.For more information on the /queue option and installation priorities, see Native Image Service.

ngen update /queue

Desinstalando ImagensUninstalling Images

Como Ngen.exe mantém uma lista de dependências, os componentes compartilhados só são removidos quando todos os assemblies que dependam dele forem removidos.Ngen.exe maintains a list of dependencies, so that shared components are removed only when all assemblies that depend on them have been removed. Além de isso, um componente compartilhado não será removido se tiver sido instalado como raiz.In addition, a shared component is not removed if it has been installed as a root.

O seguinte comando desinstala todos os cenários da raiz ClientApp.exe:The following command uninstalls all scenarios for the root ClientApp.exe:

ngen uninstall ClientApp

A ação uninstall pode ser usada para remover cenários específicos.The uninstall action can be used to remove specific scenarios. O seguinte comando desinstala todos os cenários de depuração de ClientApp.exe:The following command uninstalls all debug scenarios for ClientApp.exe:

ngen uninstall ClientApp /debug

Observação

A desinstalação de cenários /debug não desinstalará um cenário que inclua /profile e /debug.Uninstalling /debug scenarios does not uninstall a scenario that includes both /profile and /debug.

O seguinte comando desinstala todos os cenários de uma versão específica de ClientApp.exe:The following command uninstalls all scenarios for a specific version of ClientApp.exe:

ngen uninstall "ClientApp, Version=1.0.0.0"

Os seguintes comandos desinstalam todos os cenários de "ClientApp, Version=1.0.0.0, Culture=neutral, PublicKeyToken=3c7ba247adcd2081, processorArchitecture=MSIL", ou apenas o cenário de depuração desse assembly:The following commands uninstall all scenarios for "ClientApp, Version=1.0.0.0, Culture=neutral, PublicKeyToken=3c7ba247adcd2081, processorArchitecture=MSIL", or just the debug scenario for that 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, o fornecimento de uma extensão exige a execução de Ngen.exe no diretório que contém o assembly ou a especificação de um caminho completo.As with the install action, supplying an extension requires either executing Ngen.exe from the directory containing the assembly or specifying a full path.

Para obter exemplos relacionados ao serviço de imagem nativa, confira Serviço de imagem nativa.For examples relating to the native image service, see Native Image Service.

Tarefa de imagem nativaNative Image Task

A tarefa de imagem nativa é uma tarefa do Windows que gera e mantém as imagens nativas.The native image task is a Windows task that generates and maintains native images. A tarefa de imagem nativa gera e recupera automaticamente as imagens nativas para cenários com suporte.The native image task generates and reclaims native images automatically for supported scenarios. Também permite que os instaladores usem o Ngen.exe (Gerador de imagens nativas) para criar e atualizar as imagens nativas em um tempo adiado.It also enables installers to use Ngen.exe (Native Image Generator) to create and update native images at a deferred time.

A tarefa de imagem nativa é registrada uma vez para cada arquitetura de CPU com suporte em um computador, a fim de permitir a compilação para aplicativos direcionados a cada arquitetura:The native image task is registered once for each CPU architecture supported on a computer, to allow compilation for applications that target each architecture:

Nome da tarefaTask name Computadores de 32 bits32-bit computer Computadores de 64 bits64-bit computer
NET Framework NGEN v4.0.30319NET Framework NGEN v4.0.30319 SimYes SimYes
NET Framework NGEN v4.0.30319 64NET Framework NGEN v4.0.30319 64 NãoNo SimYes

A tarefa de imagem nativa está disponível no .NET Framework 4.5 e em versões posteriores ao ser executado no Windows 8 ou versão mais recente.The native image task is available in the .NET Framework 4.5 and later versions, when running on Windows 8 or later. Em versões anteriores do Windows, o .NET Framework usava o Serviço de imagem nativa.On earlier versions of Windows, the .NET Framework uses the Native Image Service.

Tempo de vida da tarefaTask Lifetime

Em geral, o Agendador de Tarefas do Windows inicia a tarefa de imagem nativa toda noite, quando o computador está ocioso.In general, the Windows Task Scheduler starts the native image task every night when the computer is idle. A tarefa procura qualquer trabalho adiado que foi enfileirado pelos instaladores de aplicativo, quaisquer solicitações de atualização de imagem nativa adiadas e qualquer criação automática de imagem.The task checks for any deferred work that is queued by application installers, any deferred native image update requests, and any automatic image creation. A tarefa conclui itens de trabalho pendentes e depois desliga.The task completes outstanding work items and then shuts down. Se o computador deixar o estado ocioso durante a execução da tarefa, a tarefa será interrompida.If the computer stops being idle while the task is running, the task stops.

Você também pode iniciar manualmente a tarefa de imagem nativa por meio da interface de usuário do Agendador de Tarefas ou por chamadas manuais ao NGen.exe.You can also start the native image task manually through the Task Scheduler UI or through manual calls to NGen.exe. Se a tarefa for iniciada por um desses métodos, ele continuará em execução quando o computador não estiver mais ocioso.If the task is started through either of these methods, it will continue running when the computer is no longer idle. As imagens criadas manualmente com o NGen.exe recebem prioridade para permitir o comportamento previsível para os instaladores de aplicativos.Images created manually by using NGen.exe are prioritized to enable predictable behavior for application installers.

Serviço de imagens nativasNative Image Service

O serviço de imagem nativa é um serviço do Windows que gera e mantém as imagens nativas.The native image service is a Windows service that generates and maintains native images. Com o serviço de imagem nativa, o desenvolvedor pode adiar a instalação e a atualização de imagens nativas para quando o computador estiver ocioso.The native image service allows the developer to defer the installation and update of native images to periods when the computer is idle.

Normalmente, o serviço de imagem nativa é iniciado pelo programa de instalação (instalador) para um aplicativo ou atualização.Normally, the native image service is initiated by the installation program (installer) for an application or update. Para ações de prioridade 3, o serviço é executado durante o período ocioso do computador.For priority 3 actions, the service executes during idle time on the computer. O serviço salva seu estado e é capaz de continuar através de várias reinicializações, se for necessário.The service saves its state and is capable of continuing through multiple reboots if necessary. É possível enfileirar várias compilações de imagem.Multiple image compilations can be queued.

O serviço também interage com o comando manual Ngen.exe.The service also interacts with the manual Ngen.exe command. Comandos manuais têm precedência sobre a atividade em segundo plano.Manual commands take precedence over background activity.

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".On Windows Vista, the name displayed for the native image service is "Microsoft.NET Framework NGEN v2.0.50727_X86" or "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".On all earlier versions of Microsoft Windows, the name is ".NET Runtime Optimization Service v2.0.50727_X86" or ".NET Runtime Optimization Service v2.0.50727_X64".

Iniciar operações adiadasLaunching Deferred Operations

Antes de iniciar uma instalação ou atualização, recomendamos pausar o serviço.Before beginning an installation or upgrade, pausing the service is recommended. Isso garante que o serviço não seja executado enquanto o instalador está copiando os arquivos ou colocando os assemblies no cache de assembly global.This ensures that the service does not execute while the installer is copying files or putting assemblies in the global assembly cache. Esta linha de comando do Ngen.exe pausa o serviço:The following Ngen.exe command line pauses the service:

ngen queue pause

Quando todas as operações adiadas tiverem sido enfileiradas, o comando a seguir permitirá que o serviço continue:When all deferred operations have been queued, the following command allows the service to resume:

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 install ou update.To defer native image generation when installing a new application or when updating a shared component, use the /queue option with the install or update actions. Estas linhas de comando do Ngen.exe instalam uma imagem nativa para um componente compartilhado e executam uma atualização de todas as raízes que foram afetadas:The following Ngen.exe command lines install a native image for a shared component and perform an update of all roots that may have been affected:

ngen install MyComponent /queue
ngen update /queue

A ação update gera novamente todas as imagens nativas que foram invalidadas, não apenas as que usam MyComponent.The update action regenerates all native images that have been invalidated, not just those that use MyComponent.

Se o seu aplicativo for composto por várias raízes, você poderá controlar a prioridade das ações adiadas.If your application consists of many roots, you can control the priority of the deferred actions. Os comandos a seguir enfileiram a instalação de três raízes.The following commands queue the installation of three roots. O Assembly1 é instalado primeiro, sem aguardar o tempo ocioso.Assembly1 is installed first, without waiting for idle time. O Assembly2 também é instalado sem esperar o tempo ocioso, mas somente após a conclusão de todas as ações de prioridade 1.Assembly2 is also installed without waiting for idle time, but after all priority 1 actions have completed. O Assembly3 é instalado quando o serviço detecta que o computador está ocioso.Assembly3 is installed when the service detects that the computer is idle.

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

Você pode forçar a ocorrência assíncrona de ações enfileiradas usando a ação executeQueuedItems.You can force queued actions to occur synchronously by using the executeQueuedItems action. Se você fornecer a prioridade opcional, essa ação afetará somente as ações enfileiradas que têm prioridade igual ou menor.If you supply the optional priority, this action affects only the queued actions that have equal or lower priority. A prioridade padrão é a 3, portanto, o seguinte comando Ngen.exe processa todas as ações em fila imediatamente e não retorna até que todas sejam concluídas:The default priority is 3, so the following Ngen.exe command processes all queued actions immediately, and does not return until they are finished:

ngen executeQueuedItems

Os comandos síncronos são executados pelo Ngen.exe e não usam o serviço de imagem nativa.Synchronous commands are executed by Ngen.exe and do not use the native image service. Você pode executar ações usando Ngen.exe enquanto o serviço de imagem nativa estiver em execução.You can execute actions using Ngen.exe while the native image service is running.

Desligamento do serviçoService Shutdown

Depois de iniciado pela execução de um comando Ngen.exe que inclui a opção /queue, o serviço é executado em segundo plano até que todas as ações sejam concluídas.After being initiated by the execution of an Ngen.exe command that includes the /queue option, the service runs in the background until all actions have been completed. O serviço salva seu estado para que ele possa continuar por várias reinicializações, se for necessário.The service saves its state so that it can continue through multiple reboots if necessary. Quando o serviço detecta que há não mais ações na fila, ele redefine seu status para que não reinicie na próxima vez que o computador for inicializado e, depois, ele se desliga.When the service detects that there are no more actions queued, it resets its status so that it will not restart the next time the computer is booted, and then it shuts itself down.

Interação do serviço com clientesService Interaction with Clients

No .NET Framework versão 2.0, a única interação com o serviço de imagem nativa ocorre por meio da ferramenta de linha de comando Ngen.exe.In the .NET Framework version 2.0, the only interaction with the native image service is through the command-line tool 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 para interagir com o serviço.Use the command-line tool in installation scripts to queue actions for the native image service and to interact with the service.

Consulte tambémSee also