Native Image Generator (NGen. exe) herdado Syntax

Essas informações neste tópico são fornecidas para usuários da.NET Framework versão 1.0 e 1.1. Para obter a sintaxe da versão 2.0, consulte NGen (Native Image Generator).

O Native Image Generator cria uma imagem nativa a partir de um assembly gerenciado e o instala no cache de imagem nativa no computador local. O cache de imagem nativa é uma área reservada de cache global de assemblies. Depois de criar uma imagem nativa para um assembly, o runtime usa automaticamente a imagem nativa sempre que ele executa o assembly. Não é necessário realizar qualquer procedimento adicional para fazer com que o tempo de execução usar uma imagem nativa. Executando o NGen. exe em um assembly permite que o assembly carregar e executar mais rapidamente, porque ele restaura o código e estruturas de dados do cache de imagem nativa em vez de gerar dinamicamente.

ngen [options] [assemblyName |assemblyPath ]

Parâmetros

Argumento	Descrição
assemblyName	O nome do assembly para o qual gerar uma imagem nativa. O assembly deve estar localizado no diretório atual. Você pode fornecer um nome parcial ou completo de um assembly. Por exemplo, você pode fornecer o nome myAssembly ou o nome completo, como myAssembly, Version=2.0.0.0, Culture=neutral, PublicKeyToken=0038abc9deabfle5. Se você desejar que o NGen. exe para localizar e usar o arquivo de política do publisher do assembly, você deve usar um nome de assembly totalmente especificado.
assemblyPath	O caminho explícito do assembly para o qual gerar uma imagem nativa. Você pode especificar um caminho completo para um assembly, como c:\applications\myApp\myApp.exe, um caminho relativo, como... \applications\myApp\myApp.exe, ou um nome de arquivo como myApp.exe. Se você especificar um nome de arquivo como myApp.exe sem um caminho completo ou relativo, o assembly deve estar localizado no diretório atual. Para permitir que o NGen. exe para um assembly como um executável de identificar e localizar o seu arquivo de configuração, você deve usar o assemblyPath argumento para especificar os assemblies com extensão. exe. Se você especificar mais de um assembly na linha de comando, apenas um dos assemblies pode ser um arquivo executável. A ferramenta aplica as propriedades de ligação do arquivo executável (base de aplicativo e quaisquer arquivos de configuração) para outros assemblies que você especificar.

Opção	Descrição
/Debug	Gera uma imagem nativa para ser usado por um depurador no modo normal de depuração.
/debugopt	Gera uma imagem nativa para ser usado por um depurador de modo otimizado de depuração do common language runtime. Consulte a documentação do depurador para obter detalhes sobre como ativar esse modo.
/Delete [assemblyName | assemblyPath | *]	Exclui as imagens nativas no cache de imagem nativa especificado assemblyName ou assemblyPath. Se você especificar o ' *' o parâmetro, a ferramenta exclui todas as imagens nativas no cache de imagem nativa. Se você não especificar um parâmetro com o /Excluir opção, a ferramenta exibe uma mensagem de erro. Quando você desinstala uma versão do.NET Framework, o processo de desinstalação usa o /Excluir opção para remover todas as imagens nativas para a versão do.NET Framework que está sendo desinstalado. Isso inclui imagens nativas criadas para.Assemblies do NET Framework em instalar o tempo, bem como quaisquer imagens nativas criadas pelo usuário para assemblies personalizados. Se você especificar o /Excluir * a opção com o /Mostrar opção, a ferramenta exibe uma lista das imagens nativas, ele exclui. Quando várias versões do.NET Framework estão instaladas no mesmo computador ao mesmo tempo, para excluir uma imagem nativa, você deve usar a mesma versão do NGen. exe que foi usado para criar a imagem nativa. Observação Essa opção afeta apenas as imagens nativas geradas com NGen. exe.Ele não tem efeito sobre os assemblies reais.
/help	Exibe sintaxe de comando e opções para a ferramenta.
/nologo	Suprime a exibição Microsoft faixa de inicialização.
/prof	Gera uma imagem nativa para ser usado por um gerador de perfil que usa código instrumentado. Consulte a documentação do seu gerador de perfil para determinar se o seu gerador de perfil requer código instrumentado.
/show	Exibe os arquivos existentes no cache de imagem nativa especificado assemblyName ou assemblyPath. Se você não especificar um argumento, a ferramenta exibe todo o conteúdo do cache de imagem nativa. Esta opção exibe informações de definição do assembly para o assembly de origem e quaisquer opções de configuração de código especial para cada imagem nativa. Se você especificar essa opção com o /Excluir * opção, a ferramenta exibe uma lista das imagens nativas, ele exclui.
/showversion	Exibe a versão do runtime que usará NGen. exe para gerar uma imagem nativa para o assembly especificado. Quando várias versões do.NET Framework estão instaladas no mesmo computador ao mesmo tempo, use esta opção para determinar a versão que usará a ferramenta. Para obter mais informações sobre como executar várias versões do runtime, consulte Lado a lado execução. Observação Esta opção não gera uma imagem nativa.
/ silencioso	Suprime a exibição de mensagens de sucesso.
/?	Exibe sintaxe de comando e opções para a ferramenta.

Comentários

NGen. exe não usa regras de probing de montagem padrão para localizar os assemblies que você especificar na linha de comando. NGen. exe procura apenas no diretório atual assemblies que você especificar. Portanto, para permitir que o NGen. exe localizar seus conjuntos, ou você deve definir seu diretório de trabalho para o diretório que contém os assemblies que você deseja criar imagens nativas para ou especificar caminhos exatos para os assemblies.

Uma imagem nativa é um arquivo contendo compilado código de máquina de processador específico. Observe que a imagem nativa, NGen. exe gera não pode ser compartilhada entre Os domínios de aplicativo. Portanto, é possível usar o NGen. exe em cenários de aplicativos que exigem conjuntos de módulos podem ser compartilhadas entre domínios de aplicativo.

Pré-Compilando assemblies com NGen. exe pode melhorar o tempo de inicialização para aplicativos, porque grande parte do trabalho necessário para executar o código foi feito antecipadamente. Portanto, é mais apropriado usar o NGen. exe para aplicativos do lado do cliente, onde você determinou que os ciclos da CPU consumidos por compilação do just-in-time (JIT) causam um desempenho mais lento.

Observação

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

Porque existem muitos fatores que afetam o tempo de inicialização de um aplicativo, você deve determinar cuidadosamente quais aplicativos se beneficiaria do uso do NGen. exe. Experimente executando uma compilação JIT e uma versão pré-compilada do assembly de um candidato no ambiente no qual ele será usado. Isso permitirá que você compare os tempos de inicialização para o mesmo assembly em execução em esquemas de compilação diferentes.

Após ter gerado uma imagem nativa para um assembly, o runtime tenta automaticamente localizar e usar esta imagem nativa sempre que ele executa o assembly. Por exemplo, se você executar um assembly em uma depuração ou cenário de criação de perfil, o runtime procura uma imagem nativa que foi gerada com o /Debug, /debugopt, ou /prof opções. Se não é possível localizar uma imagem nativa correspondente, o tempo de execução reverte para compilação padrão do JIT.

Se você executar o NGen. exe em um assembly que tem um atributo de código depurável, dependendo dos sinalizadores do atributo, a ferramenta gera automaticamente um código como se você tivesse especificado o /Debug ou /debugopt opções.

Se o NGen. exe encontrar quaisquer métodos em um assembly que não pode gerar, ele exclui da imagem nativa. Quando o tempo de execução executa este assembly, ele reverterá para a compilação JIT para os métodos que não foram incluídos na imagem nativa.

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

• A versão do.NET Framework.

• O tipo de CPU.

• A versão do sistema operacional.

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

• A identidade exata de todos os assemblies que o assembly referências (identidade de alterações de recompilação).

• Fatores de segurança.

NGen. exe registra essas informações quando ele gera uma imagem nativa. Quando você executa um assembly, o runtime procura a imagem nativa gerada com opções e configurações que correspondam ao ambiente atual do computador. O tempo de execução reverte para compilação JIT de um assembly, se ele não localizar uma imagem nativa correspondente. As seguintes alterações no ambiente e configurações de um computador causam imagens nativas para se tornar inválida:

• A versão do.NET Framework.

  Se você aplicar uma atualização para o.NET Framework, todas as imagens nativas que você criou manualmente usando o NGen. exe fique inválidas. Esses assemblies ainda serão executados, mas o tempo de execução não carregará a imagem nativa correspondente do assembly. Você deve criar manualmente as imagens nativas novas para essas montagens.

  A.NET Framework cria automaticamente novas imagens nativas para o.NET Framework, bibliotecas que ele instala.

• O tipo de CPU.

  Se você atualizar o processador do computador para uma nova família de processadores, todas as imagens nativas armazenadas no cache de imagem nativa se tornar inválidas.

• A versão do sistema operacional.

  Se a versão do sistema operacional em execução em um computador for alterado, todas as imagens nativas armazenadas no cache de imagem nativa se tornar inválidas.

• A identidade exata do assembly.

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

• A identidade exata de qualquer assemblies faz referência o assembly.

  Se você recompilar qualquer um dos assemblies que faz referência a um assembly, a imagem nativa correspondente do assembly se torna inválida.

• Fatores de segurança.

  A alteração de diretiva de segurança de máquina para restringir as permissões concedidas anteriormente a um assembly pode causar uma imagem nativa compilada anteriormente para esse assembly se tornem inválidos. Especificamente, revogar qualquer uma das seguintes permissões faz com que o nativo imagem atual do assembly se tornem inválidos:

  • Uma permissão de herança declarativa exigida por uma classe que deriva de assembly.

  • Uma permissão de tempo de vinculação declarativa exigidos por um método que chama de assembly.

  • SkipVerification permissão, se o assembly contém quaisquer métodos não verificável. Para obter mais informações sobre essa permissão, consulte o A propriedade de SecurityPermissionAttribute.SkipVerification.

  • UnmanagedCode permissão, se o assembly faz qualquer PInvoke chamadas. Para obter mais informações sobre essa permissão, consulte o A propriedade de SecurityPermissionAttribute.UnmanagedCode.

  Se você executar NGen. exe em um assembly com o code access security está desativado, a imagem nativa que ele gera se tornará inválida quando code access security está ativado. Observe que, por padrão de acesso de código segurança é no.

  Para obter informações detalhadas sobre como o common language runtime administra code access security e como usar as permissões, consulte Segurança de Acesso de código.

  Observação

  Na versão 1.0 do common language runtime, não há nenhuma criação automática ou a exclusão de imagens nativas que se tornem inválidos.Você deve criar e excluir todas as imagens nativas usando o NGen. exe manualmente.

Se você usar o NGen. exe para gerar imagens nativas para um aplicativo em tempo de instalação, você deve especificar o nome de arquivo do aplicativo e os nomes de assembly totalmente especificado do arquivo. dll arquivos o aplicativo referido no momento em que ele foi compilado. Fornecer os nomes de assembly totalmente especificado das DLLs que faz referência a um aplicativo, permite que o NGen. exe acessar os arquivos de diretiva de editor para assemblies referenciados. No futuro, se as DLLs são atualizadas e diretiva de Editor é usada no redirecionamento de versão, o NGen. exe aplicará a diretiva de editor.

Você pode obter os nomes de assembly totalmente especificado para usar executando Ildasm. exe em um aplicativo e exibindo o manifesto do assembly. O manifesto exibe o nome do assembly, versão, cultura e token de chave pública para as DLLs o aplicativo referido no momento em que ele foi compilado. Por exemplo, se você deseja criar uma imagem nativa para um aplicativo chamado ClientApp.exe que foi compilado com MyLibrary. dll, versão 1.0.0.0, culture = neutral e PublicKeyToken = 0038abc9deabfle5, use o comando ngen ClientApp.exe "myLibrary, Version=1.0.0.0, Culture=neutral, PublicKeyToken=0038abc9deabfle5".

Observe que o exemplo anterior não irá gerar nativo imagens para os assemblies que MyLibrary. dll referências. Para determinar os nomes totalmente especificados dos assemblies que referências MyLibrary. dll, execute ildasm. exe no MyLibrary. dll. Por exemplo, se você executa o ildasm. exe MyLibrary. dll e determinar o que ele faz referência a myMath.dll, a versão 1.0.0.0, cultura = neutro e PublicKeyToken = 0039def8abcbste7, use o seguinte comando para gerar imagens nativas para toda a árvore de referências de assembly do ClientApp.exe.

ngen ClientApp.exe "myLibrary, Version=1.0.0.0, Culture=neutral, PublicKeyToken=0038abc9deabfle5", "myMath, Version=1.0.0.0, Culture=neutral, PublicKeyToken=0039def8abcbste7".

Para obter mais informações sobre esse formato, consulte a seção exemplos neste tópico.

O processo de desinstalação de um aplicativo deve usar o /Excluir [assemblyName | assemblyPath] opção para remover as imagens nativas que foram criadas no momento, o aplicativo foi instalada. Você deve especificar a imagem nativa específica para excluir usando a assemblyName ou assemblyPath parâmetro. Especificando /Excluir * remove todas as imagens nativas no cache de imagem nativa; especificando o /Excluir opção sem parâmetros produz um erro.

Exemplos

O comando a seguir gera uma imagem nativa para ClientApp.exe, localizado no diretório atual. Se existir um arquivo de configuração do aplicativo, o NGen. exe irá usá-lo. A ferramenta não irá gerar imagens nativas para quaisquer DLLs que ClientApp.exe referências.

ngen ClientApp.exe

Se ClientApp.exe faz referência diretamente duas DLLs, myLibOne.dll e myLibTwo.dll, você deve fornecer o NGen. exe com os nomes de assembly totalmente especificado para essas DLLs gerar imagens nativas. Execute o ildasm. exe ClientApp.exe para determinar os nomes de assembly totalmente especificado de DLLs referenciados. O objetivo de neste exemplo, os nomes de assembly totalmente especificado de myLibOne.dll e myLibTwo.dll são "myLibOne, Version=1.0.0.0, Culture=neutral, PublicKeyToken=0038abc9deabfle5" e "myLibTwo, Version=1.0.0.0, Culture=neutral, PublicKeyToken=0038abc9deabfle5". Usando essas informações, o comando a seguir gera imagens nativas para ClientApp.exe, myLibOne.dll, e myLibTwo.dll. Se houver um arquivo de configuração para ClientApp.exe, o NGen. exe irá usá-lo. Se houver um arquivo de diretiva de editor para myLibOne.dll ou myLibTwo.dll, o NGen. exe irá usá-lo.

ngen ClientApp.exe "myLibOne, Version=1.0.0.0, Culture=neutral, PublicKeyToken=0038abc9deabfle5", "myLibTwo, Version=1.0.0.0, Culture=neutral, PublicKeyToken=0038abc9deabfle5"

No exemplo anterior, as DLLs myLibOne.dll e myLibTwo.dll pode referenciar outros assemblies. Para determinar os nomes de assembly totalmente especificado dos assemblies referenciados, execute ildasm. exe myLibOne.dll e myLibTwo.dll. para fins de neste exemplo, suponha que myLibOne.dll não faz referência a outros assemblies, e myLibTwo.dll referências "myMath, Version=1.0.0.0, Culture=neutral, PublicKeyToken=0039def8abcbste7". Usando essas informações, o comando a seguir gera a imagens nativas para toda a árvore de referências de assembly do aplicativo.

ngen ClientApp.exe "myLibOne, Version=1.0.0.0, Culture=neutral, PublicKeyToken=0038abc9deabfle5", "myMath, Version=1.0.0.0, Culture=neutral, PublicKeyToken=0039def8abcbste7", "myLibTwo, Version=1.0.0.0, Culture=neutral, PublicKeyToken=0038abc9deabfle5"

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

ngen c:\myfiles\myAssembly.exe

O comando a seguir gera uma imagem nativa para myLibrary.dll, com o caminho de especificado.

ngen c:\myfiles\myLibrary.dll

NGen. exe procura no cache de imagem nativa para excluir um assembly especificado com um nome de assembly parcial. O comando a seguir exclui todas as imagens nativas com o nome myAssembly.

ngen /delete myAssembly

O comando a seguir exclui a imagem nativa myAssembly com o nome de assembly totalmente especificado.

ngen /delete "myAssembly, Version=1.0.0.0, Culture=neutral, PublicKeyToken=0038abc9deabfle5"

O comando a seguir exibe todas as imagens nativas no cache de imagem nativa.

ngen /show

O comando a seguir exibe todas as imagens nativas no cache de imagem nativa com o nome myAssembly.

ngen /show myAssembly

O comando a seguir exibe todas as imagens nativas no cache de imagem nativa com o nome myAssembly e a versão 1.0.

ngen /show "myAssembly, version=1.0.0.0"

Consulte também

Referência

Prompt de comando Visual Studio

Conceitos

Processo de Execução Gerenciada

Como o Runtime Localiza Assemblies

Outros recursos

Ferramentas.NET Framework