Outil Native Image Generator Tool (Ngen.exe)

L'outil Native Image Generator Tool (Ngen.exe) est un outil qui améliore les performances des applications managées. Ngen.exe crée des images natives, lesquelles sont des fichiers qui contiennent le code machine spécifique au processeur compilé et les installent dans le cache des images natives sur l'ordinateur local. Le runtime peut utiliser à la place des images natives du cache à l'aide du compilateur juste-à-temps (JIT) pour compiler l'assembly d'origine.

Des modifications considérables ont été apportées à Ngen.exe dans la version 2.0 du .NET Framework :

• L'installation d'un assembly installe également ses dépendances, pour simplifier la syntaxe de Ngen.exe.

• Les images natives peuvent maintenant être partagées dans des domaines d'application.

• Une nouvelle action, update, recrée des images qui ont été invalidées.

• Les actions peuvent être différées pour leur exécution par un service qui utilise la durée d'inactivité de l'ordinateur pour générer et installer des images.

• Certaines causes d'invalidation d'images ont été éliminées.

Pour plus d'informations sur l'utilisation de Ngen.exe et du service d'images natives, consultez Service d'images natives.

ngen <action> [options]
ngen /? | /help

Actions

Le tableau ci-après décrit la syntaxe de chaque action. Pour obtenir les descriptions des parties individuelles de actionArguments, consultez les Arguments, Scenarios et les tableaux Config. Le tableau Options décrit les options et les commutateurs d'aide.

Tâche	Description
install [assemblyName | assemblyPath] [scenarios] [config] [/queue[:{1|2|3}]]	Générez des images natives pour un assembly et ses dépendances et installez les images dans le cache des images natives. Si /queue est spécifié, l'action est mise en file d'attente pour le service d'images natives. La priorité par défaut est 3.
uninstall [assemblyName | assemblyPath | *] [scenarios] [config]	Supprimez les images natives d'un assembly et ses dépendances du cache des images natives. Pour désinstaller une seule image et ses dépendances, utilisez les mêmes arguments de ligne de commande que ceux destinés à installer l'image.
update [/queue]	Mettre à jour des images natives qui sont devenues non valides. Si /queue est spécifié, les mises à jour sont mises en file d'attente pour le service d'images natives. Les mises à jour sont toujours planifiées à la priorité 3, de sorte qu'ils s'exécutent lorsque l'ordinateur est inactif.
display [assemblyName | assemblyPath]	Affichez l'état des images natives pour un assembly et ses dépendances. Si aucun argument n'est fourni, tout dans le cache des images natives est affiché.
executeQueuedItems [1|2|3]	Exécutez les travaux de compilation en attente. Si une priorité est spécifiée, les travaux de compilation présentant une priorité supérieure ou égale sont exécutés. Si aucune priorité n'est spécifiée, tous les travaux de compilation en attente sont exécutés.
queue {pause | continue | status}	Suspendez le service d'images natives, autorisez le service suspendu à continuer ou interrogez l'état du service.

Arguments

Argument	Description
assemblyName	Nom de l'assembly. Vous pouvez ou fournir un nom d'assembly partiel tel que myAssembly ou un nom complet tel que myAssembly, Version=2.0.0.0, Culture=neutral, PublicKeyToken=0038abc9deabfle5. Un seul assembly peut être spécifié par ligne de commande Ngen.exe.
assemblyPath	Chemin d'accès explicite de l'assembly. Vous pouvez spécifier un chemin d'accès complet ou relatif. Si vous spécifiez un nom de fichier sans chemin d'accès, l'assembly doit se trouver dans le répertoire actif. Un seul assembly peut être spécifié par ligne de commande Ngen.exe.

Scénarios

Scénario	Description
/Debug	Générez des images natives qui peuvent être utilisées sous un débogueur.
/Profile	Générez des images natives qui peuvent être utilisées sous un générateur de profils.
/NoDependencies	Générez le nombre minimal d'images natives requis par les options de scénario spécifiées.

Config

Configuration	Description
/ExeConfig: exePath	Utiliser la configuration de l'assembly exécutable spécifiée. Ngen.exe doit prendre les mêmes décisions que le chargeur lors de la liaison avec les dépendances. Lorsqu'un composant partagé est chargé au moment de l'exécution, à l'aide de la méthode Load, le fichier de configuration de l'application détermine les dépendances qui sont chargées pour le composant partagé, par exemple, la version d'une dépendance qui est chargée. Le commutateur /ExeConfig donne des instructions de Ngen.exe sur les dépendances qui seraient chargées au moment de l'exécution.
/AppBase: directoryPath	Lors de la localisation des dépendances, utilisez le répertoire spécifié comme base de l'application.

Options

Option	Description
/nologo	Supprimez l'affichage de la bannière de démarrage Microsoft.
/silent	Supprimez l'affichage des messages de succès.
/verbose	Affichez des informations détaillées sur le débogage. Notes En raison des limitations du système d'exploitation, cette option n'affiche pas autant d'informations supplémentaires sous Windows 98 et sous Windows Millennium.
/help, /?	Affichez la syntaxe de commande et les options de la version actuelle.

Notes

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

Ngen.exe génère des images natives pour l'assembly spécifié et toutes ses dépendances. Les dépendances sont déterminées à partir de références dans le manifeste d'assembly. Le seul scénario dans lequel vous devez installer une dépendance séparément est lorsque l'application le charge par le biais de la réflexion, par exemple en appelant la méthode System.Reflection.Assembly.Load.

Ngen.exe conserve un décompte des dépendances. Par exemple, supposons que MyAssembly.exe et YourAssembly.exe sont installés tous les deux dans le cache des images natives et qu'ils contiennent tous deux des références à OurDependency.dll. Si MyAssembly.exe est désinstallé, OurDependency.dll n'est pas désinstallée. Elle est supprimée uniquement lorsque YourAssembly.exe est également désinstallé.

Si vous générez une image native pour un assembly dans le Global Assembly Cache, spécifiez son nom complet. Consultez System.Reflection.Assembly.FullName.

Les images natives que Ngen.exe génère peuvent être partagées entre des domaines d'application. Cela signifie que vous ne pouvez pas utiliser Ngen.exe dans des scénarios d'applications qui nécessitent que les assemblys soient partagés par des domaines d'application. Pour spécifier la neutralité de domaine :

• Appliquez l'attribut LoaderOptimizationAttribute à votre application.

• Définissez la propriété System.AppDomainSetup.LoaderOptimization lorsque vous créez des informations de configuration pour un nouveau domaine d'application.

Utilisez toujours un code indépendant du domaine lors du chargement du même assembly dans plusieurs domaines d'application. Si une image native est chargée dans un domaine d'application non partagé après avoir été chargée dans un domaine partagé, elle ne peut pas être utilisée.

Génération d'images dans différents scénarios

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. Plusieurs images peuvent être générées, selon les scénarios d'utilisation.

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 ou /Profile. S'il ne trouve pas d'image native correspondante, le runtime revient à la compilation JIT standard. La seule façon de déboguer des images natives consiste à créer une image native avec l'option /Debug.

L'action uninstall reconnaît également les scénarios, vous pouvez ainsi désinstaller tous les scénarios ou uniquement les scénarios sélectionnés.

Détermination des cas d'utilisation des images natives

Les images natives peuvent fournir des améliorations des performances dans deux domaines : l'amélioration de l'utilisation de la mémoire et la réduction du temps de démarrage.

Amélioration de l'utilisation de la mémoire

Les images natives peuvent considérablement améliorer l'utilisation de la mémoire lorsque le code est partagé entre des processus. Les images natives sont des fichiers PE Windows, ainsi, une seule copie d'un fichier .dll peut être partagée par plusieurs processus ; en revanche, le code natif produit par le compilateur JIT est stocké dans la mémoire privée et ne peut pas être partagé.

Les applications qui sont exécutées sous des services Terminal Server peuvent également bénéficier de pages de code partagées.

En outre, ne pas charger le compilateur JIT économise une quantité de mémoire fixe pour chaque instance d'application.

Démarrage d'application plus rapide

La précompilation des assemblys avec Ngen.exe peut améliorer le temps de démarrage de certaines applications. En général, des gains peuvent être réalisés lorsque les applications partagent des assemblys de composants, parce qu'après que le démarrage de la première application, les composants partagés sont déjà chargés pour les applications suivantes. Le démarrage à froid, dans lequel tous les assemblys d'une application doivent être chargés à partir du disque dur, ne bénéficie pas autant des images natives parce que le temps d'accès au disque dur prédomine.

La liaison matérielle peut affecter le temps de démarrage, car toutes les images qui sont liées par une liaison matérielle à l'assembly d'application principale doivent être chargées en même temps.

Importance des adresses de base d'assembly

Étant donné que les images natives sont des fichiers PE Windows, elles sont soumises aux mêmes problèmes de redéfinition que les autres fichiers exécutables. Le coût du réadressage en termes de performances est encore plus marqué si la liaison matérielle est utilisée.

Pour définir l'adresse de base d'une image native, utilisez l'option appropriée de votre compilateur pour définir l'adresse de base de l'assembly. Ngen.exe utilise cette adresse de base pour l'image native.

Vous pouvez utiliser un outil tel que dumpbin.exe pour visualiser l'adresse de base par défaut d'une image native.

Résumé des considérations d'utilisation

Les considérations générales suivantes et les considérations sur l'application peuvent vous aider à décider si cela vaut la peine d'évaluer des images natives pour votre application :

• Les images natives se chargent plus vite que MSIL, parce qu'elles ne nécessitent pas beaucoup d'activités de démarrage, comme la compilation JIT et la vérification de la sécurité de type.

• Les images natives requièrent un jeu de travail initial réduit, parce qu'elles n'ont pas besoin d'un compilateur JIT.

• Les images natives activent le partage de code entre des processus.

• Les images natives requièrent plus d'espace de disque dur que les assemblys MSIL et leur génération peut nécessiter beaucoup de temps.

• Les images natives doivent être gérées.

  • Elles doivent être créées à nouveau lorsque l'assembly d'origine ou l'une de ses dépendances est pris en charge.

  • Un seul assembly peut avoir besoin de plusieurs images natives pour les utiliser dans différentes applications ou différents scénarios. Par exemple, les informations de configuration dans deux applications peuvent donner lieu à des décisions différentes en matière de liaison pour le même assembly dépendant.

  • Les images natives doivent être créées par un administrateur, c'est-à-dire à partir d'un compte Windows du groupe Administrateurs.

Outre ces considérations générales, la nature de votre application doit être prise en compte lorsque vous déterminez si les images natives peuvent fournir un gain de performances :

• Si votre application s'exécute dans un environnement qui utilise beaucoup de composants partagés, les images natives permettent aux composants d'être partagés entre plusieurs processus.

• Si votre application utilise plusieurs domaines d'application, les images natives permettent à des pages de codes d'être partagées entre des domaines.

  Notes

  Dans les versions 1.0 et 1.1 de .NET Framework, les images natives ne peuvent pas être partagées entre des domaines d'application. Ce n'est pas le cas dans la version 2.0.

• Si votre application est exécutée sous Terminal Server, les images natives autorisent le partage des pages de code.

• Les applications volumineuses profitent généralement de la compilation dans des images natives. Les petites applications n'en bénéficient généralement pas.

• Pour les applications à durée d'exécution longue, la compilation JIT à l'exécution est légèrement plus performante que les images natives. (La liaison matérielle peut atténuer cette différence de performances dans une certaine mesure.)

Liaison matérielle

La liaison matérielle augmente le débit et réduit la taille du jeu de travail pour les images natives. L'inconvénient de la liaison matérielle est que toutes les images qui sont liées par liaison matérielle à un assembly doivent être chargées lorsque l'assembly est chargé. Cela peut augmenter considérablement le temps de démarrage d'une application volumineuse.

La liaison matérielle convient aux dépendances chargées dans tous les scénarios aux performances critiques de votre application. Comme dans tous les aspects d'utilisation des images natives, les mesures de performances prudentes constituent le seul moyen de déterminer si la liaison matérielle améliore les performances de votre application.

Les attributs DependencyAttribute et DefaultDependencyAttribute vous permettent de fournir des indications sur la liaison matérielle à Ngen.exe.

Spécification d'une indication sur la liaison pour une dépendance

Appliquez DependencyAttribute à un assembly pour indiquer la probabilité qu'une dépendance spécifiée soit chargée. System.Runtime.CompilerServices.LoadHint.Always indique que la liaison matérielle est appropriée, Default indique que la valeur par défaut de la dépendance doit être utilisée et Sometimes indique que la liaison matérielle n'est pas appropriée.

Le code suivant affiche les attributs d'un assembly qui possède deux dépendances. La première dépendance (Assembly1) est un candidat approprié pour la liaison matérielle et la deuxième (Assembly2) ne l'est pas.

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)];

Le nom de l'assembly n'inclut pas l'extension de nom de fichier. Les noms complets peuvent être utilisés.

Spécification d'une indication sur la liaison par défaut pour un assembly

Les indications sur la liaison par défaut sont nécessaires uniquement pour les assemblys qui seront utilisés immédiatement et fréquemment par toute application qui possède une dépendance pour ceux-ci. Appliquez DefaultDependencyAttribute avec System.Runtime.CompilerServices.LoadHint.Always aux assemblys de ce type pour spécifier que la liaison matérielle doit être utilisée.

Microsoft utilise DefaultDependencyAttribute pour spécifier que la liaison matérielle est la valeur par défaut d'un très petit nombre d'assemblys dans le .NET Framework, tel que mscorlib.dll.

Dépannage

Pour confirmer que les images natives sont utilisées par votre application, vous pouvez utiliser Assembly Binding Log Viewer (Fuslogvw.exe). Sélectionnez Images natives dans la zone Catégories de journaux dans la fenêtre de la visionneuse du journal des liaisons. Fuslogvw.exe fournit des informations sur la raison pour laquelle une image native a été rejetée.

Vous pouvez utiliser l'Assistant Débogage managé (MDA) JitCompilationStart pour déterminer quand le compilateur JIT commence à compiler une fonction.

Traitement différé

La génération d'images natives pour une application très volumineuse peut prendre beaucoup de temps. De même, les modifications apportées à un composant partagé ou aux paramètres de l'ordinateur peuvent nécessiter la mise à jour de nombreuses images natives. Les actions install et update possèdent une option /queue qui met en file d'attente l'opération pour exécution différée par le service d'images natives. En outre, Ngen.exe possède des actions queue et executeQueuedItems qui offrent un certain contrôle sur le service. Pour plus d'informations, consultez Service d'images natives.

Images natives et compilation JIT

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.

En outre, les images natives ne sont pas utilisées si l'assembly a été mis à niveau ou si l'image a été invalidée pour une raison quelconque.

Images non valides

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.

• Version du système d'exploitation, si le changement se fait de la famille Windows 9x vers la famille Windows NT.

• 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 à l'aide de Ngen.exe deviennent non valides. Pour cette raison, toutes les mises à jour du .NET Framework exécutent la commande Ngen Update, afin de s'assurer que toutes les images natives sont régénérées. .NET Framework crée automatiquement de nouvelles images natives pour les bibliothèques .NET Framework qu'il installe.

• Version du système d'exploitation, si le changement se fait de la famille Windows 9x vers la famille Windows NT.

  Par exemple, si la version du système d'exploitation s'exécutant sur un ordinateur change de Windows 98 en Windows XP, toutes les images natives stockées dans le cache des images natives deviennent non valides. Toutefois, si le système d'exploitation change de Windows 2000 en Windows XP, les images ne sont pas invalidées.

• 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 mettez à jour un assembly managé, toutes les images natives qui dépendent directement ou indirectement de cet assembly deviennent non valides et doivent être régénérées. Cela inclut des références ordinaires et des dépendances liées par une liaison matérielle. À chaque fois qu'une mise à jour de logiciel est appliquée, le programme d'installation doit exécuter une commande Ngen Update pour garantir que toutes les images natives dépendantes sont régénérées.

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

  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

Exemples

La commande suivante génère une image native pour ClientApp.exe, située dans le répertoire actif, puis installe l'image dans le cache des images natives. S'il existe un fichier de configuration pour l'assembly, Ngen.exe l'utilise. En outre, les images natives sont générées pour tous les fichiers .dll auxquels ClientApp.exe fait référence.

ngen install ClientApp.exe

Une image installée avec Ngen.exe est également appelée une racine. Une racine peut être une application ou un composant partagé.

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

ngen install c:\myfiles\MyAssembly.exe

Lors de la localisation des assemblys et de leurs dépendances, Ngen.exe utilise la même logique de détection que celle utilisée par le Common Language Runtime. Par défaut, le répertoire qui contient ClientApp.exe est utilisé comme répertoire de base de l'application et toute la détection d'assembly commence dans ce répertoire. Vous pouvez substituer ce comportement en utilisant l'option /AppBase.

Un assembly peut posséder une dépendance sans référence, par exemple, s'il charge un fichier .DLL en utilisant la méthode System.Reflection.Assembly.Load. Vous pouvez créer une image native pour un fichier .dll de ce type en utilisant des informations de configuration pour l'assembly d'application, avec l'option /ExeConfig. La commande suivante génère une image native pour MyLib.dll, à l'aide des informations de configuration de MyApp.exe.

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

Les assemblys installés grâce à cette méthode ne sont pas supprimés lorsque l'application est supprimée.

Pour désinstaller une dépendance, utilisez les mêmes options de ligne de commande que celles qui ont servi à l'installer. La commande suivante désinstalle MyLib.dll de l'exemple précédent.

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

Pour créer une image native d'un assembly dans le Global Assembly Cache, utilisez le nom complet de l'assembly. Par exemple :

ngen install "ClientApp, Version=1.0.0.0, Culture=neutral, 
  PublicKeyToken=3c7ba247adcd2081, processorArchitecture=MSIL"

NGen.exe génère un ensemble d'images séparé pour chaque scénario que vous installez. Par exemple, les commandes suivantes installent un jeu complet d'images natives pour des opérations normales, un autre jeu complet pour le débogage et un troisième pour la génération de profils :

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

Affichage du cache des images natives

Une fois que les images natives sont installées dans le cache, elles peuvent être affichées à l'aide de Ngen.exe. La commande suivante affiche toutes les images natives dans le cache des images natives.

ngen display

L'action display répertorie d'abord tous les assemblys racine, puis toutes les images natives sur l'ordinateur.

Utilisez le nom simple d'un assembly pour afficher uniquement les informations de cet assembly. La commande suivante affiche toutes les images natives du cache des images natives qui correspondent au nom partiel MyAssembly, leurs dépendances et toutes les racines qui ont une dépendance de MyAssembly :

ngen display MyAssembly

Connaître les racines qui dépendent d'un assembly de composant partagé est utile pour mesurer l'impact d'une action update après la mise à niveau du composant partagé.

Si vous spécifiez l'extension de fichier d'un assembly, vous devez spécifier le chemin d'accès ou exécuter Ngen.exe à partir du répertoire qui contient l'assembly :

ngen display c:\myApps\MyAssembly.exe

La commande suivante affiche toutes les images natives du cache des images natives dont le nom est MyAssembly et la version 1.0.0.0.

ngen display "myAssembly, version=1.0.0.0"

Mise à jour d'images

Les images sont généralement mises à jour après la mise à niveau d'un composant partagé. Pour mettre à jour toutes les images natives qui ont été modifiées ou dont les dépendances ont été modifiées, utilisez l'action update sans arguments.

ngen update

La mise à jour de toutes les images peut être un processus long. Vous pouvez mettre en file d'attente les mises à jour pour exécution par le service d'images natives en utilisant l'option /queue. Pour plus d'informations sur l'option /queue et les priorités d'installation, consultez Service d'images natives.

ngen update /queue

Désinstallation d'images

Ngen.exe gère une liste de dépendances, de sorte que les composants partagés soient supprimés uniquement lorsque tous les assemblys qui dépendent d'eux ont été supprimés. En outre, un composant partagé n'est pas supprimé s'il a été installé comme racine.

La commande suivante désinstalle tous les scénarios de la racine ClientApp.exe :

ngen uninstall ClientApp

L'action uninstall peut être utilisée pour supprimer des scénarios spécifiques. La commande suivante désinstalle tous les scénarios de débogage de ClientApp.exe :

ngen uninstall ClientApp /debug

La commande suivante désinstalle tous les scénarios d'une version spécifique de ClientApp.exe :

ngen uninstall "ClientApp, Version=1.0.0.0"

Les commandes suivantes désinstallent tous les scénarios de "ClientApp, Version=1.0.0.0, Culture=neutral, PublicKeyToken=3c7ba247adcd2081, processorArchitecture=MSIL", ou seulement le scénario de débogage de cet 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

Comme avec l'action install, le fait de fournir une extension requiert l'exécution de Ngen.exe à partir du répertoire contenant l'assembly ou spécifiant un chemin d'accès complet.

Pour obtenir des exemples concernant le service d'images natives, consultez Service d'images natives.

Voir aussi

Référence

Outils du .NET Framework
Invite de commandes du Kit de développement SDK

Concepts

Service d'images natives
Compilation du MSIL en code natif
Méthode de localisation des assemblys par le runtime