Sintassi preesistente del generatore di immagini native (Ngen.exe)
Aggiornamento: novembre 2007
Le informazioni del presente argomento sono destinate agli utenti delle versioni 1.0 e 1.1 di .NET Framework. Per la sintassi della versione 2.0, vedere Generatore di immagini native (Ngen.exe).
Il generatore di immagini native consente di creare un'immagine nativa da un assembly gestito e di installarla nella cache delle immagini native nel computer locale. La cache delle immagini native è un'area riservata della Global Assembly Cache. Dopo aver creato un'immagine nativa per un assembly, l'immagine nativa viene utilizzata automaticamente dal runtime a ogni esecuzione dell'assembly. Non è necessario eseguire procedure aggiuntive per far sì che il runtime utilizzi un'immagine nativa. L'esecuzione di Ngen.exe su un assembly consente di caricare ed eseguire l'assembly più rapidamente perché il codice e le strutture di dati vengono ripristinati dalla cache delle immagini native anziché essere generati in modo dinamico.
ngen [options] [assemblyName |assemblyPath ]
Parametri
Argomento |
Descrizione |
|---|---|
Nomeassembly |
Nome dell'assembly per il quale si desidera generare un'immagine nativa. L'assembly deve trovarsi nella directory corrente. È possibile fornire un nome di assembly parzialmente specificato quale myAssembly o un nome di assembly completamente specificato, quale myAssembly, Version=2.0.0.0, Culture=neutral, PublicKeyToken=0038abc9deabfle5. Per far sì che il file dei criteri dell'editore di un assembly venga individuato e utilizzato da Ngen.exe, è necessario utilizzare un nome di assembly completamente specificato. |
Percorsoassembly |
Percorso esplicito dell'assembly per il quale si desidera generare un'immagine nativa. È possibile specificare un percorso completo di un assembly, ad esempio c:\applications\myApp\myApp.exe, un percorso relativo quale ..\applications\myApp\myApp.exe o un nome file quale myApp.exe. Se si specifica un nome file quale myApp.exe senza un percorso completo o relativo, l'assembly deve trovarsi nella directory corrente. Per consentire a Ngen.exe di identificare un assembly come un eseguibile e individuarne il rispettivo file di configurazione, è necessario utilizzare l'argomento assemblyPath per specificare assembly con un'estensione EXE. Se si specificano più assembly alla riga di comando, uno solo di essi può essere un file eseguibile. Lo strumento consente di applicare le proprietà di associazione del file eseguibile (applicazione di base e qualsiasi file di configurazione) agli altri assembly specificati. |
Opzione |
Descrizione |
|---|---|
/debug |
Consente di generare un'immagine nativa per un debugger che opera in modalità di debug normale. |
/debugopt |
Consente di generare un'immagine nativa per un debugger che opera in modalità di debug ottimizzata di Common Language Runtime. Per dettagli su come attivare tale modalità, consultare la documentazione del debugger. |
/delete [assemblyName | assemblyPath | *] |
Consente di eliminare le immagini native presenti nella cache delle immagini native relative all'argomento assemblyName o assemblyPath specificato. Se si specifica il parametro '*', tutte le immagini native contenute nella cache dell'immagine nativa verranno eliminate. Se non si specifica un parametro con l'opzione /delete, verrà visualizzato un messaggio di errore. Quando si disinstalla una versione di .NET Framework, nel processo di disinstallazione viene utilizzata l'opzione /delete per rimuovere tutte le immagini native relative alla versione di .NET Framework da disinstallare. Vengono pertanto eliminate anche le immagini native create per assembly .NET Framework in fase di installazione, nonché tutte le immagini native create dall'utente per assembly personalizzati. Se si specifica l'opzione /delete * con l'opzione /show, viene visualizzato un elenco delle immagini native eliminate. Quando nello stesso computer sono installate contemporaneamente più versioni di .NET Framework, per eliminare un'immagine nativa è necessario utilizzare la stessa versione di Ngen.exe utilizzata per creare l'immagine nativa. Nota Questa opzione ha effetto solo sulle immagini native generate con Ngen.exe e non sugli assembly reali. |
/help |
Visualizza la sintassi e le opzioni dei comandi dello strumento. |
/nologo |
Evita la visualizzazione del messaggio di avvio Microsoft. |
/prof |
Consente di generare un'immagine nativa per un profiler che utilizza codice dotato di strumenti. Per stabilire se il profiler richiede codice dotato di strumenti, consultare la documentazione del profiler. |
/show |
Consente di visualizzare i file esistenti nella cache delle immagini relativi all'argomento assemblyName o assemblyPath specificato. Se non si specifica alcun argomento, lo strumento visualizza l'intero contenuto della cache delle immagini native. Questa opzione consente di visualizzare le informazioni di definizione dell'assembly di origine e ogni particolare opzione di configurazione del codice per ciascuna immagine nativa. Se si specifica questa opzione con l'opzione /delete*, viene visualizzato un elenco delle immagini native eliminate. |
/showversion |
Consente di visualizzare la versione del runtime utilizzata da Ngen.exe per generare un'immagine nativa per l'assembly specificato. Quando nello stesso computer vengono installate contemporaneamente più versioni di .NET Framework, utilizzare questa opzione per determinare la versione che verrà utilizzata dallo strumento. Per ulteriori informazioni sull'esecuzione di più versioni del runtime, vedere Esecuzione contemporanea di diverse versioni. Nota Questa opzione non consente di generare un'immagine nativa. |
/silent |
Evita la visualizzazione dei messaggi di operazione riuscita. |
/? |
Visualizza la sintassi e le opzioni dei comandi dello strumento. |
Note
In Ngen.exe non vengono utilizzate le regole standard di ricerca di assembly per individuare gli assembly specificati nella riga di comando. La ricerca degli assembly specificati viene effettuata solo nella directory corrente. Per consentire a Ngen.exe di individuare gli assembly, è quindi necessario impostare la directory di lavoro sulla directory contenente gli assembly per cui si desidera creare immagini native oppure specificare percorsi esatti degli assembly.
Un'immagine nativa è un file contenente codice macchina compilato specifico del processore. L'immagine nativa generata da Ngen.exe non può essere condivisa tra Domini applicazione. Non è pertanto possibile utilizzare Ngen.exe in scenari di applicazioni che richiedono la condivisione di assembly tra più domini applicazione.
La precompilazione degli assembly con Ngen.exe può ridurre il tempo di avvio delle applicazioni perché la maggior parte del lavoro necessario per l'esecuzione del codice viene svolta in anticipo. È pertanto preferibile utilizzare Ngen.exe per quelle applicazioni sul lato client le cui prestazioni risultano compromesse dall'impegno di CPU richiesto dalla compilazione JIT.
Nota
Per eseguire Ngen.exe, è necessario disporre di privilegi amministrativi.
Dal momento che i fattori che influenzano il tempo di avvio di un'applicazione sono numerosi, è necessario individuare con cura le applicazioni per cui può risultare vantaggioso servirsi di Ngen.exe. Provare a eseguire una versione compilata con JIT e una versione precompilata di un assembly nell'ambiente in cui l'assembly verrà utilizzato. Questa operazione consente di confrontare i tempi di avvio dello stesso assembly eseguito in schemi di compilazione diversi.
Una volta generata un'immagine nativa di un assembly, il runtime tenterà automaticamente di individuarla e utilizzarla ogni volta che viene eseguito l'assembly. Se ad esempio si esegue un assembly in uno scenario di profiling o di debug, il runtime cercherà un'immagine nativa generata con le opzioni /debug, /debugopt o /prof. Se non è possibile individuare un'immagine nativa corrispondente, verrà ripristinata la compilazione JIT standard.
Se si esegue Ngen.exe su un assembly che dispone di un attributo per la generazione di codice predisposto al debug, a seconda dei flag dell'attributo, lo strumento si comporterà come se fossero state specificate le opzioni /debug o /debugopt.
Se Ngen.exe individua in un assembly metodi che non possono essere generati, li esclude dall'immagine nativa. Quando il runtime eseguirà questo assembly, si avvarrà della compilazione JIT per i metodi che non sono stati inclusi nell'immagine nativa.
Quando si utilizza Ngen.exe per creare un'immagine nativa di un assembly, l'output dipenderà dalle opzioni specificate alla riga di comando e da determinate impostazioni del computer. tra cui:
Versione di .NET Framework.
Tipo di CPU.
La versione del sistema operativo.
Identità esatta dell'assembly (l'identità cambia ad ogni ricompilazione).
Identità esatta di tutti gli assembly a cui l'assembly fa riferimento (l'identità cambia ad ogni ricompilazione).
Fattori di protezione.
Quando genera un'immagine nativa, Ngen.exe registra queste informazioni. Quando si esegue un assembly, il runtime cerca l'immagine nativa generata con le opzioni e le impostazioni che corrispondono all'ambiente corrente del computer. Se non viene individuata un'immagine nativa corrispondente, viene ripristinata la compilazione JIT di un assembly. Le modifiche alle impostazioni e all'ambiente di un computer che rendono non valide le immagini native sono le seguenti:
Versione di .NET Framework.
Se viene eseguito un aggiornamento di .NET Framework, tutte le immagini native create manualmente utilizzando Ngen.exe non saranno più valide. L'esecuzione degli assembly proseguirà, ma il runtime non caricherà l'immagine nativa corrispondente dell'assembly. Sarà necessario creare nuove immagini native per gli assembly.
.NET Framework crea automaticamente nuove immagini native per le librerie di .NET Framework installate.
Tipo di CPU.
Se si effettua l'aggiornamento del processore di un computer a una nuova famiglia di processori, tutte le immagini native memorizzate nella cache dell'immagine nativa diventeranno non valide.
La versione del sistema operativo.
Se si cambia la versione del sistema operativo in esecuzione, tutte le immagini native memorizzate nella cache dell'immagine nativa diventeranno non valide.
Identità esatta dell'assembly.
Se si ricompila un assembly, l'immagine nativa corrispondente diventerà non valida.
Identità esatta di tutti gli assembly a cui fa riferimento l'assembly.
Se si ricompilano gli assembly a cui fa riferimento un assembly, l'immagine nativa corrispondente diventerà non valida.
Fattori di protezione.
La modifica dei criteri di protezione del computer per limitare le autorizzazioni concesse in precedenza a un assembly può rendere non valida un'immagine nativa compilata in precedenza per l'assembly in questione. In particolare, l'immagine nativa corrente diventerà non valida se si richiama una delle seguenti autorizzazioni:
Un'autorizzazione di ereditarietà dichiarativa richiesta da una classe da cui deriva l'assembly.
Un'autorizzazione in fase di collegamento dichiarativa richiesta da un metodo chiamato dall'assembly.
L'autorizzazione SkipVerification, se l'assembly contiene metodi non verificabili. Per ulteriori informazioni su questa autorizzazione, vedere la Proprietà SecurityPermissionAttribute.SkipVerification.
L'autorizzazione UnmanagedCode, se l'assembly effettua chiamate PInvoke. Per ulteriori informazioni su questa autorizzazione, vedere la Proprietà SecurityPermissionAttribute.UnmanagedCode.
Se si esegue Ngen.exe su un assembly in cui è stata disattivata la protezione dall'accesso di codice, l'immagine nativa generata diventerà non valida quanto la protezione dall'accesso di codice viene attivata. Per impostazione predefinita, la protezione dall'accesso di codice è attivata.
Per informazioni dettagliate sulla gestione della protezione dall'accesso di codice da parte di Common Language Runtime e su come utilizzare le autorizzazioni, vedere Protezione dall'accesso di codice
Nota
Nella versione 1.0 di Common Language Runtime non è prevista la creazione o l'eliminazione automatica di immagini native non più valide. È necessario creare ed eliminare manualmente tutte le immagini native utilizzando Ngen.exe.
Se si utilizza Ngen.exe per generare immagini native per un'applicazione in fase di installazione, è necessario specificare il nome del file dell'applicazione e i nomi di assembly completamente specificati dei file DLL a cui faceva riferimento l'applicazione al momento della compilazione. Se vengono forniti i nomi di assembly completamente specificati delle DLL a cui un'applicazione fa riferimento, Ngen.exe può accedere ai file dei criteri dell'editore per gli assembly a cui viene fatto riferimento. Nel futuro, se si aggiornano le DLL e si utilizza il criterio dell'editore per il reindirizzamento della versione, in Ngen.exe verrà applicato il criterio dell'editore.
È possibile ottenere i nomi di assembly completamente specificati da utilizzare eseguendo Ildasm.exe su un'applicazione e visualizzandone il manifesto assembly. Nel manifesto viene visualizzato il nome dell'assembly, la versione, la lingua e il token della chiave pubblica per le DLL a cui ha fatto riferimento l'applicazione al momento della compilazione. Se ad esempio si desidera creare un'immagine nativa per un'applicazione denominata ClientApp.exe, compilata con le informazioni myLibrary.dll, version 1.0.0.0, culture=neutral e PublicKeyToken=0038abc9deabfle5, utilizzare il comando ngen ClientApp.exe "myLibrary, Version=1.0.0.0, Culture=neutral, PublicKeyToken=0038abc9deabfle5".
Nell'esempio precedente non verranno generate immagini native per gli assembly a cui fa riferimento myLibrary.dll. Per determinare i nomi completamente specificati degli assembly a cui fa riferimento myLibrary.dll, eseguire Ildasm.exe su myLibrary.dll. Se, ad esempio, si esegue Ildasm.exe su myLibrary.dll e si determina che fa riferimento a myMath.dll, version 1.0.0.0, culture=neutral e PublicKeyToken=0039def8abcbste7, utilizzare il comando riportato di seguito per generare immagini native per l'intera struttura dei riferimenti agli assembly di 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".
Per ulteriori informazioni sui formati, vedere la sezione Esempi più avanti in questo argomento.
Il processo di disinstallazione per un'applicazione deve utilizzare l'opzione /delete [assemblyName | assemblyPath] per rimuovere le immagini native create al momento dell'installazione dell'applicazione. È necessario indicare l'immagine nativa specifica da eliminare utilizzando il parametro assemblyName o assemblyPath. Se si specifica /delete *, tutte le immagini native contenute nella cache dell'immagine nativa verranno rimosse. Se si specifica invece l'opzione /delete senza parametri, verrà prodotto un errore.
Esempi
Il comando riportato di seguito consente di generare un'immagine nativa per ClientApp.exe, che si trova nella directory corrente. Se un file di configurazione esiste per l'applicazione, verrà utilizzato da Ngen.exe. Non verranno generate immagini native per le DLL a cui ClientApp.exe fa riferimento.
ngen ClientApp.exe
Se ClientApp.exe fa riferimento direttamente a due DLL, myLibOne.dll e myLibTwo.dll, sarà necessario fornire a Ngen.exe i nomi di assembly completamente specificati per le DLL per generare immagini native apposite. Eseguire Ildasm.exe su ClientApp.exe per determinare i nomi di assembly completamente specificati delle DLL a cui viene fatto riferimento. Ai fini di questo esempio, i nomi di assembly completamente specificati di myLibOne.dll e myLibTwo.dll sono "myLibOne, Version=1.0.0.0, Culture=neutral, PublicKeyToken=0038abc9deabfle5" e "myLibTwo, Version=1.0.0.0, Culture=neutral, PublicKeyToken=0038abc9deabfle5". Utilizzando queste informazioni, il comando consente di generare immagini native per ClientApp.exe, myLibOne.dll e myLibTwo.dll. Se un file di configurazione esiste per ClientApp.exe, verrà utilizzato da Ngen.exe. Se esiste un file dei criteri dell'editore per myLibOne.dll o myLibTwo.dll, verrà utilizzato da Ngen.exe.
ngen ClientApp.exe "myLibOne, Version=1.0.0.0, Culture=neutral, PublicKeyToken=0038abc9deabfle5", "myLibTwo, Version=1.0.0.0, Culture=neutral, PublicKeyToken=0038abc9deabfle5"
Nell'esempio precedente le DLL myLibOne.dll e myLibTwo.dll potevano fare riferimento ad altri assembly. Per determinare i nomi di assembly completamente specificati degli assembly a cui viene fatto riferimento, eseguire Ildasm.exe su myLibOne.dll e myLibTwo.dll. Ai fini dell'esempio, si suppone che myLibOne.dll non faccia riferimento ad altri assembly e myLibTwo.dll faccia riferimento a "myMath, Version=1.0.0.0, Culture=neutral, PublicKeyToken=0039def8abcbste7". Utilizzando queste informazioni, il comando riportato di seguito consente di generare immagini native per l'intera struttura dei riferimenti dell'assembly dell'applicazione.
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"
Il comando riportato di seguito consente di generare un'immagine nativa per myAssembly.exe con il percorso specificato.
ngen c:\myfiles\myAssembly.exe
Il comando riportato di seguito consente di generare un'immagine nativa per myLibrary.dll, con il percorso specificato.
ngen c:\myfiles\myLibrary.dll
Ngen.exe cerca nella cache dell'immagine nativa per eliminare un assembly specificato con un nome di assembly parziale. Il comando riportato di seguito consente di eliminare tutte le immagini native con il nome myAssembly.
ngen /delete myAssembly
Il comando riportato di seguito consente di eliminare l'immagine nativa myAssembly con il nome di assembly completamente specificato.
ngen /delete "myAssembly, Version=1.0.0.0, Culture=neutral, PublicKeyToken=0038abc9deabfle5"
Il comando riportato di seguito consente di visualizzare tutte le immagini native presenti nella cache delle immagini native.
ngen /show
Il comando riportato di seguito consente di visualizzare tutte le immagini native presenti nella cache delle immagini native e denominate myAssembly.
ngen /show myAssembly
Il comando riportato di seguito consente di visualizzare tutte le immagini native presenti nella cache delle immagini native denominate myAssembly e la cui versione sia 1.0.
ngen /show "myAssembly, version=1.0.0.0"
Vedere anche
Concetti
Compilazione di MSIL in codice nativo
Come il runtime individua gli assembly