Outil Native Image Generator Tool (Ngen.exe), syntaxe héritée (legacy)

Article
08/10/2011

Les informations contenues dans cette rubrique sont destinées aux utilisateurs des versions 1.0 et 1.1 du .NET Framework. Pour la syntaxe de la version 2.0, consultez Ngen.exe (Native Image Generator).

L'outil Native Image Generator Tool (Générateur d'images natives) crée une image native à partir d'un assembly managé et l'installe dans le cache des images natives sur l'ordinateur local. Le cache des images natives est une zone réservée du Global Assembly Cache. Une fois que vous avez créé une image native pour un assembly, le runtime l'utilise automatiquement chaque fois qu'il exécute l'assembly. Aucune procédure supplémentaire n'est nécessaire pour que le runtime utilise une image native. L'exécution de Ngen.exe sur un assembly permet un chargement et une exécution plus rapides de ce dernier, car il restaure le code et les structures de données à partir du cache des images natives au lieu de les générer dynamiquement.

ngen [options] [assemblyName |assemblyPath ]

Paramètres

Argument	Description
assemblyName	Nom de l'assembly pour lequel une image native doit être générée. L'assembly doit être situé dans le répertoire actif. Vous pouvez indiquer un nom d'assembly partiellement spécifié, tel que myAssembly ou un nom d'assembly complètement spécifié, tel que myAssembly, Version=2.0.0.0, Culture=neutral, PublicKeyToken=0038abc9deabfle5. Vous devez utiliser un nom d'assembly complètement spécifié si vous souhaitez que Ngen.exe recherche et utilise le fichier de stratégie de l'éditeur d'un assembly.
assemblyPath	Chemin d'accès explicite de l'assembly pour lequel une image native doit être générée. Vous pouvez spécifier un chemin d'accès complet à un assembly, tel que c:\applications\myApp\myApp.exe, un chemin d'accès relatif tel que .. \applications\myApp\myApp.exe, ou un nom de fichier tel que myApp.exe. Si vous spécifiez un nom de fichier tel que myApp.exe sans chemin d'accès complet ni relatif, l'assembly doit se trouver dans le répertoire actif. Pour permettre à Ngen.exe d'identifier un assembly en tant qu'exécutable et de rechercher son fichier de configuration, vous devez utiliser l'argument assemblyPath pour spécifier des assemblys avec une extension .exe. Si vous spécifiez plusieurs assemblys dans la ligne de commande, un seul assembly peut être un fichier exécutable. L'outil applique les propriétés de liaison du fichier exécutable (base de l'application et tous les fichiers de configuration) aux autres assemblys spécifiés.

assemblyName

Nom de l'assembly pour lequel une image native doit être générée. L'assembly doit être situé dans le répertoire actif. Vous pouvez indiquer un nom d'assembly partiellement spécifié, tel que myAssembly ou un nom d'assembly complètement spécifié, tel que myAssembly, Version=2.0.0.0, Culture=neutral, PublicKeyToken=0038abc9deabfle5. Vous devez utiliser un nom d'assembly complètement spécifié si vous souhaitez que Ngen.exe recherche et utilise le fichier de stratégie de l'éditeur d'un assembly.

assemblyPath

Chemin d'accès explicite de l'assembly pour lequel une image native doit être générée. Vous pouvez spécifier un chemin d'accès complet à un assembly, tel que c:\applications\myApp\myApp.exe, un chemin d'accès relatif tel que .. \applications\myApp\myApp.exe, ou un nom de fichier tel que myApp.exe.

Si vous spécifiez un nom de fichier tel que myApp.exe sans chemin d'accès complet ni relatif, l'assembly doit se trouver dans le répertoire actif.

Pour permettre à Ngen.exe d'identifier un assembly en tant qu'exécutable et de rechercher son fichier de configuration, vous devez utiliser l'argument assemblyPath pour spécifier des assemblys avec une extension .exe.

Si vous spécifiez plusieurs assemblys dans la ligne de commande, un seul assembly peut être un fichier exécutable. L'outil applique les propriétés de liaison du fichier exécutable (base de l'application et tous les fichiers de configuration) aux autres assemblys spécifiés.

Option	Description
/debug	Génère une image native destinée à être utilisée par un débogueur en mode débogage normal.
/debugopt	Génère une image native destinée à être utilisée par un débogueur en mode débogage optimisé du Common Language Runtime. Consultez la documentation de votre débogueur pour plus d'informations sur l'activation de ce mode.
/delete [assemblyName \| assemblyPath \| *]	Supprime les images natives dans le cache des images natives pour les arguments assemblyName ou assemblyPath spécifiés. Si vous spécifiez le paramètre '', l'outil supprime toutes les images natives dans le cache des images natives. Si vous ne spécifiez pas de paramètre avec l'option /delete, l'outil affiche un message d'erreur. Lorsque vous désinstallez une version du .NET Framework, le processus de désinstallation utilise l'option /delete* pour supprimer toutes les images natives de la version du .NET Framework désinstallée. Cela comprend les images natives créées pour les assemblys .NET Framework au moment de l'installation ainsi que celles créées par l'utilisateur pour des assemblys personnalisés. Si vous spécifiez l'option /delete * avec l'option /show, l'outil affiche une liste des images natives qu'il supprime. Lorsque plusieurs versions du .NET Framework sont installées sur le même ordinateur à la fois et que vous souhaitez supprimer une image native, vous devez utiliser la même version de Ngen.exe que celle utilisée pour créer ces images natives. Remarque Cette option affecte seulement les images natives générées avec Ngen.exe.Il n'a aucun effet sur les assemblys réels.
/help	Affiche la syntaxe et les options de commande de l'outil.
/nologo	Supprime l'affichage de la bannière de démarrage Microsoft.
/prof	Génère une image native destinée à être utilisée par un générateur de profils utilisant du code instrumenté. Consultez la documentation de votre générateur de profils pour déterminer si celui-ci requiert du code instrumenté.
/show	Affiche les fichiers existants dans le cache des images natives pour les arguments assemblyName ou assemblyPath spécifiés. Si vous ne spécifiez aucun argument, l'outil affiche l'ensemble du contenu du cache des images natives. Cette option affiche les informations relatives à la définition de l'assembly source, ainsi que les options particulières de configuration du code pour chaque image native. Si vous spécifiez cette option avec l'option /delete *, l'outil affiche une liste des images natives qu'il supprime.
/showversion	Affiche la version du runtime utilisé par Ngen.exe pour générer une image native pour l'assembly spécifié. Lorsque plusieurs versions du .NET Framework sont installées sur le même ordinateur à la fois et que vous souhaitez supprimer une image native, utilisez cette option pour déterminer la version utilisée par l'outil. Pour plus d'informations sur l'exécution de plusieurs versions du runtime, consultez Exécution côte à côte. Remarque Cette option ne génère pas d'image native.
/silent	Supprime l'affichage des messages indiquant la réussite des opérations.
/?	Affiche la syntaxe et les options de commande de l'outil.

Notes

Ngen.exe n'utilise pas de règles de test d'assembly standard pour rechercher les assemblys que vous spécifiez sur la ligne de commande. Ngen.exe ne recherche les assemblys que vous spécifiez que dans le répertoire actif. Par conséquent, pour permettre à Ngen.exe de trouver vos assemblys, vous devez faire en sorte que votre répertoire de travail corresponde au répertoire qui contient les assemblys pour lesquels vous souhaitez créer des images natives ou spécifier les chemins d'accès exacts aux assemblys.

Une image native est un fichier contenant du code machine compilé spécifique au processeur. Notez que l'image native générée par Ngen.exe ne peut pas être partagée par des domaines d'application. Par conséquent, vous ne pouvez pas utiliser Ngen.exe dans des scénarios d'applications qui exigent que les assemblys soient partagés par des domaines d'application.

La précompilation des assemblys à l'aide de Ngen.exe peut améliorer le temps de démarrage des applications, car une bonne part du travail requis pour l'exécution du code s'effectue à l'avance. Par conséquent, il est préférable d'utiliser Ngen.exe pour les applications côté client lorsque vous réalisez que les cycles de processeur consommés par la compilation JIT (Just-in-time) entraînent une baisse des performances.

Remarque
Pour exécuter Ngen.exe, vous devez disposer de privilèges d'administrateur.

Étant donné qu'il y a de nombreux facteurs qui affectent le temps de démarrage d'une application, vous devriez déterminer avec soin quelles applications bénéficieraient de l'utilisation de Ngen.exe. Expérimentez en exécutant à la fois une version compilée JIT et une version pré-compilée d'un assembly de candidat dans l'environnement dans lequel il sera utilisé. Cela vous permettra de comparer les temps de démarrage d'un même assembly dans des schémas de compilation différents.

Une fois que vous avez généré une image native pour un assembly, le runtime essaie automatiquement de la localiser et de l'utiliser chaque fois qu'il exécute l'assembly. Par exemple, si vous exécutez un assembly dans un scénario de débogage ou de génération de profils, le runtime recherche une image native générée à l'aide des options /debug, /debugopt ou /prof. S'il ne trouve pas d'image native correspondante, le runtime revient à la compilation JIT standard.

Si vous exécutez Ngen.exe sur un assembly qui possède un attribut de code pouvant être débogué, selon les indicateurs de cet attribut, l'outil génère automatiquement le code comme si vous aviez spécifié les options /debug ou /debugopt.

Si, dans un assembly, Ngen.exe rencontre des méthodes qu'il ne peut pas générer, il les exclut de l'image native. Lorsque le runtime exécute cet assembly, il revient à la compilation JIT pour les méthodes non incluses dans l'image native.

Lorsque vous utilisez Ngen.exe pour créer une image native d'un assembly, le résultat dépend des options de ligne de commande spécifiées et de certains paramètres de votre ordinateur. Ces paramètres sont les suivants :

Version du .NET Framework.
Type CPU.
Version du système d'exploitation.
Identité exacte de l'assembly (toute nouvelle compilation modifie l'identité).
Identité exacte de tous les assemblys auxquels l'assembly fait référence (toute nouvelle compilation modifie l'identité).
Facteurs de sécurité.

Ngen.exe enregistre ces informations lorsqu'il génère une image native. Lorsque vous exécutez un assembly, le runtime recherche l'image native générée à l'aide des options et des paramètres correspondant à l'environnement actif de l'ordinateur. Le runtime revient à la compilation JIT d'un assembly, s'il ne trouve pas d'image native correspondante. Les modifications suivantes des paramètres et de l'environnement d'un ordinateur entraînent la perte de validité des images natives :

Version du .NET Framework.

Si vous appliquez une mise à jour au .NET Framework, toutes les images natives que vous avez créées manuellement à l'aide de Ngen.exe deviennent non valides. Ces assemblys continuent de fonctionner, mais le runtime ne charge pas l'image native correspondante de l'assembly. Vous devez créer de nouvelles images natives manuellement pour ces assemblys.

.NET Framework crée automatiquement de nouvelles images natives pour les bibliothèques .NET Framework qu'il installe.
Type CPU.

Si le processeur d'un ordinateur est mis à niveau vers une nouvelle famille de processeurs, toutes les images natives stockées dans le cache des images natives deviennent non valides.
Version du système d'exploitation.

Si la version du système d'exploitation s'exécutant sur un ordinateur change, toutes les images natives stockées dans le cache des images natives deviennent non valides.
Identité exacte de l'assembly.

Si vous recompilez un assembly, l'image native correspondante de l'assembly devient non valide.
Identité exacte des assemblys auxquels l'assembly fait référence.

Si vous recompilez un des assemblys référencé par un assembly, l'image native correspondante de l'assembly devient non valide.

Facteurs de sécurité.

Le changement de la stratégie de sécurité d'un ordinateur pour restreindre les autorisations précédemment accordées à un assembly peut entraîner la perte de validité d'une image native précédemment compilée pour cet assembly. Plus précisément, la révocation de n'importe laquelle des autorisations suivantes entraîne la perte de validité de l'image native active d'un assembly :

Une autorisation déclarative d'héritage demandée par une classe dont dérive l'assembly.
Une autorisation déclarative durant l'édition de liens demandée par une méthode appelée par l'assembly.
L'autorisation SkipVerification, si l'assembly contient des méthodes non vérifiables. Pour plus d'informations sur cette autorisation, consultez SecurityPermissionAttribute.SkipVerification, propriété.
L'autorisation UnmanagedCode, si l'assembly effectue des appels PInvoke. Pour plus d'informations sur cette autorisation, consultez SecurityPermissionAttribute.UnmanagedCode.

Si vous exécutez Ngen.exe sur un assembly dont la sécurité d'accès du code est désactivée, l'image native qu'il génère devient non valide lorsque la sécurité d'accès du code est activée. Notez que la sécurité d'accès du code est activée par défaut.

Pour plus d'informations sur la façon dont le Common Language Runtime administre la sécurité d'accès du code et sur l'utilisation des autorisations, consultez Sécurité d'accès du code

Remarque
Dans la version 1.0 du Common Language Runtime, il n'existe pas de création ni de suppression automatique des images natives qui deviennent non valides.Vous devez créer et supprimer manuellement toutes les images natives à l'aide de Ngen.exe.

Si vous utilisez Ngen.exe pour générer des images natives pour une application au moment de l'installation, vous devez spécifier le nom du fichier de l'application et les noms d'assemblys complètement spécifiés des fichiers .dll référencés par l'application au moment de la compilation. L'indication des noms d'assemblys complètement spécifiés des fichiers DLL référencés par une application permet à Ngen.exe d'accéder aux fichiers de stratégie de l'éditeur des assemblys référencés. Par la suite, si les fichiers DLL sont mis à jour et si la stratégie de l'éditeur est utilisée pour une redirection de version, Ngen.exe applique la stratégie de l'éditeur.

Vous pouvez obtenir les noms d'assemblys complètement spécifiés à utiliser en exécutant Ildasm.exe sur une application et en affichant son manifeste d'assembly. Le manifeste affiche le nom de l'assembly, la version, la culture et le jeton de clé publique des fichiers DLL référencés par l'application au moment de la compilation. Par exemple, si vous souhaitez créer une image native pour une application appelée ClientApp.exe compilée avec myLibrary.dll, version 1.0.0.0, culture=neutral et PublicKeyToken=0038abc9deabfle5, utilisez la commande ngen ClientApp.exe "myLibrary, Version=1.0.0.0, Culture=neutral, PublicKeyToken=0038abc9deabfle5".

Notez que l'exemple précédent ne génère pas d'image native pour les assemblys référencés par myLibrary.dll. Pour déterminer les noms complètement spécifiés des assemblys que myLibrary.dll référence, exécutez Ildasm.exe sur myLibrary.dll. Par exemple, si vous exécutez Ildasm.exe sur myLibrary.dll et déterminez qu'il référence myMath.dll, version 1.0.0.0, culture=neutral et PublicKeyToken=0039def8abcbste7, utilisez la commande suivante pour générer des images natives pour l'arborescence entière de ClientApp.exe de références d'assembly.

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

Pour plus d'informations sur ce format, consultez la section Exemples, plus loin dans cette rubrique.

Le processus de désinstallation pour une application doit utiliser /delete [assemblyName | assemblyPath] option pour supprimer les images natives créées lors de l'installation de l'application. Vous devez indiquer l'image native spécifique à supprimer à l'aide du paramètre assemblyName ou assemblyPath. Si vous spécifiez /delete *, toutes les images natives sont supprimées dans le cache des images natives ; si vous spécifiez l'option /delete sans paramètre, une erreur est générée.

Exemples

La commande suivante génère une image native pour l'application ClientApp.exe, située dans le répertoire actif. S'il existe un fichier de configuration pour l'application, Ngen.exe l'utilise. L'outil ne génère pas d'images natives pour les DLL référencées par ClientApp.exe.

ngen ClientApp.exe

Si ClientApp.exe référence directement deux DLL, myLibOne.dll et myLibTwo.dll, vous devez indiquer à Ngen.exe les noms d'assemblys complètement spécifiés pour ces DLL afin de leur générer des images natives. Exécutez Ildasm.exe sur ClientApp.exe pour déterminer les noms d'assemblys complètement spécifiés des fichiers DLL référencés. Dans le cas de cet exemple, les noms d'assemblys complètement spécifiés de myLibOne.dll et myLibTwo.dll sont "myLibOne, Version=1.0.0.0, Culture=neutral, PublicKeyToken=0038abc9deabfle5" et "myLibTwo, Version=1.0.0.0, Culture=neutral, PublicKeyToken=0038abc9deabfle5". À l'aide de ces informations, la commande suivante génère des images natives pour ClientApp.exe, myLibOne.dll et myLibTwo.dll. S'il existe un fichier de configuration pour l'application ClientApp.exe, Ngen.exe l'utilise. S'il existe un fichier de stratégie de l'éditeur pour myLibOne.dll ou myLibTwo.dll, Ngen.exe l'utilise.

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

Dans l'exemple précédent, les fichiers DLL myLibOne.dll et myLibTwo.dll peuvent référencer d'autres assemblys. Pour déterminer les noms d'assemblys complètement spécifiés des assemblys référencés, exécutez Ildasm.exe sur myLibOne.dll et myLibTwo.dll. Dans le cas de cet exemple, on suppose que myLibOne.dll ne référence aucun autre assembly et que myLibTwo.dll référence "myMath, Version=1.0.0.0, Culture=neutral, PublicKeyToken=0039def8abcbste7". À l'aide de ces informations, la commande suivante génère des images natives pour toute l'arborescence des références d'assembly de l'application.

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"

La commande suivante génère une image native pour myAssembly.exe en fonction du chemin d'accès spécifié.

ngen c:\myfiles\myAssembly.exe

La commande suivante génère une image native pour myLibrary.dll, en fonction du chemin d'accès spécifié.

ngen c:\myfiles\myLibrary.dll

Ngen.exe regarde dans le cache des images natives pour supprimer un assembly spécifié avec un nom d'assembly partiel. La commande suivante supprime toutes les images natives nommées myAssembly.

ngen /delete myAssembly

La commande suivante supprime l'image native myAssembly avec le nom d'assembly complètement spécifié.

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

La commande suivante affiche toutes les images natives du cache des images natives.

ngen /show

La commande suivante affiche toutes les images natives du cache des images natives dont le nom est myAssembly.

ngen /show myAssembly

La commande suivante affiche toutes les images natives contenues dans le cache des images natives dont le nom est myAssembly et la version 1.0.

ngen /show "myAssembly, version=1.0.0.0"

Voir aussi

Outil Native Image Generator Tool (Ngen.exe), syntaxe héritée (legacy)

Paramètres

Notes

Exemples

Voir aussi

Référence

Concepts

Autres ressources

Ressources supplémentaires