Native Image Generator (Ngen.exe)

Native Image Generator (Ngen.exe) ist ein Tool, das die Leistung verwalteter Anwendungen verbessert. Ngen.exe erstellt systemeigene Abbilder, also Dateien mit kompiliertem prozessorspezifischem Computercode, die daraufhin im Cache für systemeigene Abbilder auf dem lokalen Computer installiert werden. Die Laufzeit kann systemeigene Abbilder aus dem Cache nutzen und muss nicht den JIT-Compiler (Just-In-Time) verwenden, um die ursprüngliche Assembly zu kompilieren.

Ngen.exe weist in .NET Framework, Version 2.0, deutliche Unterschiede auf:

• Mit der Installation einer Assembly werden auch ihre Abhängigkeiten installiert, und die Syntax von Ngen.exe wird vereinfacht.

• Systemeigene Abbilder können jetzt für mehrere Anwendungsdomänen verwendet werden.

• Die neue Aktion update erstellt ungültig gewordene Abbilder neu.

• Sie können Aktionen verzögern und von einem Dienst ausführen lassen, der die Leerlaufzeiten auf dem Computer nutzt, um Abbilder zu generieren und zu installieren.

• Einige Ursachen für die Ungültigkeit von Abbildern wurden eliminiert.

Zusätzliche Informationen zur Verwendung von Ngen.exe und dem Dienst für systemeigene Abbilder finden Sie unter Dienst für systemeigene Abbilder.

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

Aktionen

In der folgenden Tabelle ist die Syntax für die einzelnen Aktionen dargestellt. Beschreibungen der einzelnen Teile von actionArguments finden Sie in den Tabellen Arguments, Scenarios und Config. In der Tabelle Options werden die options und die Hilfeschalter beschrieben.

Aktion	Beschreibung
install [assemblyName | assemblyPath] [scenarios] [config] [/queue[:{1|2|3}]]	Generiert systemeigene Abbilder für eine Assembly und ihre Abhängigkeiten und installiert die Abbilder im Cache für systemeigene Abbilder. Wenn /queue angegeben wird, wird die Aktion in die Warteschlange des Dienstes für systemeigene Abbilder eingereiht. Die Standardpriorität ist 3.
uninstall [assemblyName | assemblyPath | *] [scenarios] [config]	Löscht die systemeigenen Abbilder einer Assembly und ihre Abhängigkeiten aus dem Cache für systemeigene Abbilder. Verwenden Sie zum Deinstallieren eines einzelnen Abbilds und seiner Abhängigkeiten dieselben Befehlszeilenargumente wie beim Installieren des Abbilds.
update [/queue]	Aktualisiert systemeigene Abbilder, die ungültig geworden sind. Wenn /queue angegeben wird, werden die Aktualisierungen in die Warteschlange des Dienstes für systemeigene Abbilder gestellt. Aktualisierungen werden immer mit Priorität 3 geplant, sodass sie zu Leerlaufzeiten des Computers ausgeführt werden.
display [assemblyName | assemblyPath]	Zeigt den Zustand der systemeigenen Abbilder für eine Assembly und ihre Abhängigkeiten an. Wenn kein Argument angegeben wird, wird der gesamte Inhalt des Caches für systemeigene Abbilder angezeigt.
executeQueuedItems [1|2|3]	Führt die in der Warteschlange enthaltenen Kompilierungsaufträge aus. Wenn eine Priorität angegeben wird, werden Kompilierungsaufträge mit höherer oder gleicher Priorität ausgeführt. Wenn keine Priorität angegeben wird, werden alle in die Warteschlange eingereihten Kompilierungsaufträge ausgeführt.
queue {pause | continue | status}	Hält den Dienst für systemeigene Abbilder an, setzt den angehaltenen Dienst fort oder fragt den Dienststatus ab.

Argumente

Argument	Beschreibung
assemblyName	Der Name der Assembly. Sie können den Assemblynamen entweder teilweise, z. B. myAssembly, oder als vollständigen Anzeigenamen, z. B. myAssembly, Version=2.0.0.0, Culture=neutral, PublicKeyToken=0038abc9deabfle5, angeben. In jeder Befehlszeile von Ngen.exe kann nur eine Assembly angegeben werden.
assemblyPath	Der explizite Pfad der Assembly. Sie können einen vollständigen oder relativen Pfad angeben. Wenn Sie einen Dateinamen ohne Pfad angeben, muss sich die Assembly im aktuellen Verzeichnis befinden. In jeder Befehlszeile von Ngen.exe kann nur eine Assembly angegeben werden.

Szenarios

Szenario	Beschreibung
/Debug	Generiert systemeigene Abbilder, die unter einem Debugger verwendet werden können.
/Profile	Generiert systemeigene Abbilder, die unter einem Profiler verwendet werden können.
/NoDependencies	Generiert die Mindestanzahl systemeigener Abbilder, die von den angegebenen Einsatzszenarios benötigt werden.

Konfiguration

Konfiguration	Beschreibung
/ExeConfig: exePath	Verwendet die Konfiguration der angegebenen ausführbaren Assembly. Ngen.exe muss beim Binden an Abhängigkeiten die gleichen Entscheidungen wie das Ladeprogramm treffen. Wenn eine freigegebene Komponente zur Laufzeit mit der Load-Methode geladen wird, ermittelt die Konfigurationsdatei der Anwendung die Abhängigkeiten, die für die freigegebene Komponente geladen werden, beispielsweise die Version einer geladenen Abhängigkeit. Über den Schalter /ExeConfig erhält Ngen.exe Anweisungen dazu, welche Abhängigkeiten zur Laufzeit geladen werden.
/AppBase: directoryPath	Verwendet das angegebene Verzeichnis beim Suchen nach Abhängigkeiten als Anwendungsbasis.

Optionen

Option	Beschreibung
/nologo	Unterdrückt die Anzeige des Startbanners von Microsoft.
/silent	Unterdrückt die Anzeige von Erfolgsmeldungen.
/verbose	Zeigt ausführliche Informationen zum Debuggen an. Hinweis Aufgrund von Beschränkungen im Betriebssystem werden in Windows 98 und Windows Millennium Edition durch diese Option nicht so viele zusätzliche Informationen angezeigt.
/help, /?	Zeigt die Befehlssyntax sowie Optionen für die aktuelle Version an.

Hinweise

Um Ngen.exe ausführen zu können, müssen Sie über Administratorrechte verfügen.

Ngen.exe generiert systemeigene Abbilder für die angegebene Assembly und alle ihre Abhängigkeiten. Abhängigkeiten werden anhand von Verweisen im Assemblymanifest bestimmt. Eine Abhängigkeit müssen Sie nur in einem Szenario separat installieren, in dem die Abhängigkeit von der Anwendung mittels Reflektion geladen wird, z. B. durch Aufrufen der System.Reflection.Assembly.Load-Methode.

Ngen.exe erfasst die Anzahl der Abhängigkeiten. Angenommen, MyAssembly.exe und YourAssembly.exe sind im Cache für systemeigene Abbilder installiert, und beide verfügen über Verweise auf OurDependency.dll. Wenn MyAssembly.exe deinstalliert wird, wird OurDependency.dll nicht deinstalliert. Die Deinstallation erfolgt erst, wenn auch YourAssembly.exe deinstalliert wird.

Wenn Sie ein systemeigenes Abbild für eine Assembly im globalen Assemblycache generieren, geben Sie deren Anzeigenamen an. Weitere Informationen finden Sie unter System.Reflection.Assembly.FullName.

Die mit Ngen.exe generierten systemeigenen Abbilder können für andere Anwendungsdomänen freigegeben werden. Dies bedeutet, dass Ngen.exe in Anwendungsszenarios verwendet werden kann, in denen Assemblys von mehreren Anwendungsdomänen gemeinsam genutzt werden. So geben Sie Domänenneutralität an:

• Weisen Sie der Anwendung das LoaderOptimizationAttribute-Attribut zu.

• Legen Sie die System.AppDomainSetup.LoaderOptimization-Eigenschaft fest, wenn Sie Setupinformationen für eine neue Anwendungsdomäne erstellen.

Verwenden Sie immer domänenneutralen Code, wenn Sie dieselbe Assembly in mehrere Anwendungsdomänen laden. Wenn ein systemeigenes Abbild in eine nicht gemeinsam genutzte Anwendungsdomäne geladen wird, nachdem es in eine gemeinsam genutzte Domäne geladen wurde, kann es nicht verwendet werden.

Generieren von Abbildern für verschiedene Szenarios

Nachdem Sie ein systemeigenes Abbild für eine Assembly generiert haben, wird dies bei jedem Aufruf der Assembly automatisch von Common Language Runtime gesucht und verwendet. Je nach Anwendungsszenario können mehrere Abbilder generiert werden.

Wenn Sie eine Assembly z. B. in einem Debug- oder Profilerszenario ausführen, sucht die Laufzeit nach einem systemeigenen Abbild, das mit der Option /Debug oder der Option /Profile generiert wurde. Wenn kein entsprechendes systemeigenes Abbild gefunden wurde, wird die Laufzeit auf die standardmäßige JIT-Kompilierung zurückgesetzt. Die einzige Möglichkeit zum Debuggen systemeigener Abbilder besteht darin, ein systemeigenes Abbild mit der Option /Debug zu erstellen.

Die Aktion uninstall erkennt auch Szenarios, sodass Sie alle oder nur ausgewählte Szenarios deinstallieren können.

Wann sollten systemeigene Abbilder verwendet werden?

Systemeigene Abbilder bieten Leistungsverbesserungen in zwei Bereichen: verbesserte Arbeitsspeichernutzung und beschleunigte Startzeit.

Verbesserte Arbeitsspeichernutzung

Systemeigene Abbilder können die Arbeitsspeichernutzung entscheidend verbessern, wenn Code zwischen Prozessen freigegeben wird. Systemeigene Abbilder werden in Form von Windows PE-Dateien gespeichert. Eine einzelne Version einer DLL-Datei kann also von mehreren Prozessen gemeinsam genutzt werden. Vom JIT-Compiler erstellter systemeigener Code wird demgegenüber im privaten Speicher abgelegt und kann nicht freigegeben werden.

Unter Terminaldiensten ausgeführte Anwendungen können ebenfalls von freigegebenen Codepages profitieren.

Wenn der JIT-Compiler nicht geladen wird, wird außerdem pro Anwendungsinstanz eine feste Speichergröße eingespart.

Schnellerer Anwendungsstart

Durch das Vorkompilieren von Assemblys mit Ngen.exe kann die Startzeit einiger Anwendungen beschleunigt werden. Zeit lässt sich im Allgemeinen dadurch gewinnen, dass Anwendungen Komponentenassemblys gemeinsam nutzen, denn nachdem die erste Anwendung gestartet wurde, sind die freigegebenen Komponenten für nachfolgende Anwendungen bereits geladen. Bei einem Kaltstart, bei dem alle Assemblys einer Anwendung von der Festplatte geladen werden müssen, fällt der Nutzen systemeigener Abbilder geringer aus, da die Zugriffszeiten auf die Festplatte den Zeitgewinn wieder aufheben.

Die feste Bindung kann die Startzeit verlangsamen, da alle Abbilder, die eine feste Bindung an die Hauptassembly der Anwendung aufweisen, gleichzeitig geladen werden müssen.

Wichtigkeit der Basisadressen von Assemblys

Da es sich bei systemeigenen Abbildern um Windows PE-Dateien handelt, unterliegen sie im Hinblick auf die Zurücksetzung denselben Voraussetzungen wie andere ausführbare Dateien. Die Leistungseinbußen infolge der Umsetzung treten bei der festen Bindung sogar noch stärker hervor.

Um die Basisadresse für ein systemeigenes Abbild anzugeben, verwenden Sie die geeignete Compileroption zum Festlegen der Basisadresse für die Assembly. Ngen.exe verwendet diese Basisadresse für das systemeigene Abbild.

Mit einem Tool wie dumpbin.exe können Sie die bevorzugte Basisadresse eines systemeigenen Abbilds anzeigen.

Überlegungen zur Anwendung

Anhand der folgenden allgemeinen und anwendungsspezifischen Überlegungen können Sie feststellen, ob es sich lohnt, systemeigene Abbilder für die Anwendung auszuwerten:

• Systemeigene Abbilder werden schneller geladen als MSIL, da dafür zahlreiche Startaktivitäten, z. B. JIT-Kompilierung und Überprüfungen der Typsicherheit, nicht mehr notwendig sind.

• Systemeigene Abbilder erfordern kleinere anfängliche Workingsets, da der JIT-Compiler nicht benötigt wird.

• Systemeigene Abbilder ermöglichen die gemeinsame Codenutzung zwischen Prozessen.

• Für systemeigene Abbilder wird mehr Festplattenspeicher als für MSIL-Assemblys benötigt, und für ihre Generierung ist möglicherweise wesentlich mehr Zeit erforderlich.

• Systemeigene Abbilder müssen verwaltet werden.

  • Abbilder müssen neu generiert werden, wenn die ursprüngliche Assembly oder eine ihrer Abhängigkeiten verarbeitet wird.

  • Für eine einzelne Assembly sind möglicherweise mehrere systemeigene Abbilder zur Verwendung in verschiedenen Anwendungen oder verschiedenen Szenarios erforderlich. Beispielsweise können die Konfigurationsinformationen in zwei Anwendungen zu unterschiedlichen Bindungsentscheidungen für dieselbe abhängige Assembly führen.

  • Systemeigene Abbilder müssen von einem Administrator generiert werden, d. h. ausgehend von einem Windows-Konto der Administratorgruppe.

Zusätzlich zu diesen allgemeinen Überlegungen muss bei der Frage, ob systemeigene Abbilder einen Leistungsgewinn bringen, auch die Art der Anwendung berücksichtigt werden:

• Wenn die Anwendung in einer Umgebung ausgeführt wird, in der zahlreiche freigegebene Komponenten verwendet werden, können die Komponenten bei Verwendung systemeigener Abbilder von mehreren Prozessen gemeinsam genutzt werden.

• Wenn die Anwendung mehrere Anwendungsdomänen verwendet, ermöglichen systemeigene Abbilder die gemeinsame Nutzung von Codepages zwischen Domänen.

  Hinweis

  In .NET Framework, Version 1.0 und 1.1, können systemeigene Abbilder nicht zwischen Anwendungsdomänen freigegeben werden. Dies trifft auf Version 2.0 nicht zu.

• Wenn die Anwendung unter Terminalserver ausgeführt wird, lassen systemeigene Abbilder die Freigabe von Codepages zu.

• Bei umfangreicheren Anwendungen ist die Kompilierung in systemeigene Abbilder normalerweise von Vorteil; bei kleineren Anwendungen dagegen nicht.

• Bei Anwendungen mit langer Laufzeit weist die JIT-Kompilierung zur Laufzeit eine etwas bessere Leistung als systemeigene Abbilder auf. (Die feste Bindung kann diesen Leistungsunterschied in gewissem Umfang abschwächen.)

Feste Bindung

Die feste Bindung erhöht den Durchsatz und reduziert die Größe des Workingsets für systemeigene Abbilder. Der Nachteil der festen Bindung besteht darin, dass sämtliche Abbilder mit fester Bindung an eine Assembly beim Laden der Assembly ebenfalls geladen werden müssen. Dies kann die Startzeit bei umfangreichen Anwendungen deutlich verlängern.

Die feste Bindung eignet sich für Abhängigkeiten, die in allen leistungskritischen Szenarios der Anwendung geladen werden. Wie bereits bei anderen Verwendungsmöglichkeiten systemeigener Abbilder stellen sorgfältige Leistungsmessungen auch hier den einzigen Indikator dafür dar, ob die Anwendungsleistung durch feste Bindung verbessert wird.

Über das DependencyAttribute-Attribut und das DefaultDependencyAttribute-Attribut können Sie Ngen.exe Hinweise zur Verwendung der festen Bindung übermitteln.

Angeben eines Bindungshinweises für eine Abhängigkeit

Durch Anwenden von DependencyAttribute auf eine Assembly geben Sie die Wahrscheinlichkeit an, dass eine bestimmte Abhängigkeit geladen wird. System.Runtime.CompilerServices.LoadHint.Always gibt an, dass die feste Bindung geeignet ist, Default gibt an, dass die Standardeinstellung für die Abhängigkeit verwendet werden soll, und Sometimes gibt an, dass die feste Bindung nicht geeignet ist.

Im folgenden Code werden die Attribute für eine Assembly veranschaulicht, die über zwei Abhängigkeiten verfügt. Die erste Abhängigkeit (Assembly1) ist ein geeigneter Kandidat für die feste Bindung und die zweite Abhängigkeit (Assembly2) nicht.

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

Der Assemblyname enthält keine Dateinamenerweiterung. Anzeigenamen können verwendet werden.

Angeben eines standardmäßigen Bindungshinweises für eine Assembly

Standardmäßige Bindungshinweise werden nur für Assemblys benötigt, die direkt und häufig von einer Anwendung verwendet werden, die über eine Abhängigkeit zu diesen Assemblys verfügt. Wenden Sie DefaultDependencyAttribute mit System.Runtime.CompilerServices.LoadHint.Always auf diese Assemblys an, um anzugeben, dass die feste Bindung verwendet werden soll.

Microsoft verwendet DefaultDependencyAttribute, um die feste Bindung als Standard für eine verhältnismäßig kleine Anzahl von Assemblys in .NET Framework anzugeben, beispielsweise mscorlib.dll.

Problembehandlung

Um zu überprüfen, ob systemeigene Abbilder von der Anwendung verwendet werden, können Sie den Assembly Binding Log Viewer-Tool (Fuslogvw.exe) verwenden. Wählen Sie im Fenster des Binding Log Viewer-Tools im Feld Kategorien protokollieren die Option Systemeigene Abbilder aus. Fuslogvw.exe liefert Informationen dazu, warum ein systemeigenes Abbild abgelehnt wurde.

Mit dem JitCompilationStart-MDA (Managed Debugging Assistant, Assistent für verwaltetes Debuggen) können Sie bestimmen, wann der JIT-Compiler mit der Kompilierung einer Funktion beginnt.

Verzögertes Verarbeiten

Die Generierung von systemeigenen Abbildern für eine sehr große Anwendung kann sehr viel Zeit beanspruchen. Entsprechend können Änderungen an einer freigegebenen Komponente oder an den Computereinstellungen die Aktualisierung vieler systemeigener Abbilder nach sich ziehen. Die Aktion install und die Aktion update verfügen über eine Option /queue, über die Sie den Vorgang zur verzögerten Ausführung in eine Warteschlange einreihen und vom Dienst für systemeigene Abbilder verarbeiten lassen können. Außerdem verfügt Ngen.exe über die Aktion queue und die Aktion executeQueuedItems, mit der der Dienst in gewissem Umfang gesteuert werden kann. Weitere Informationen finden Sie unter Dienst für systemeigene Abbilder.

Systemeigene Abbilder und JIT-Kompilierung

Wenn Ngen.exe auf Methoden in einer Assembly trifft, die von diesem Programm nicht erstellt werden können, werden diese Methoden aus dem systemeigenen Abbild ausgeschlossen. Wenn die Laufzeit diese Assembly ausführt, werden die nicht im systemeigenen Abbild enthaltenen Methoden auf JIT-Kompilierung zurückgesetzt.

Darüber hinaus werden systemeigene Abbilder nicht verwendet, wenn die Assembly aktualisiert wurde bzw. das Abbild aus irgendeinem Grund ungültig geworden ist.

Ungültige Abbilder

Wenn Sie mit Ngen.exe ein systemeigenes Abbild einer Assembly erstellen, hängt die Ausgabe von den Optionen in der Befehlszeile und bestimmten Computereinstellungen ab. Dies betrifft folgende Einstellungen:

• Version von .NET Framework.

• Die Version des Betriebssystems, wenn der Wechsel von der Windows 9x-Familie zur Windows NT-Familie durchgeführt wird.

• Genaue Identität der Assembly (Rekompilierung ändert die Identität).

• Genaue Identität aller Assemblys, auf die die Assembly verweist (Rekompilierung ändert die Identität).

• Sicherheitsfaktoren.

Diese Daten werden beim Generieren eines systemeigenen Abbilds von Ngen.exe aufgezeichnet. Beim Ausführen einer Assembly sucht die Common Language Runtime nach dem systemeigenen Abbild, das mit den Optionen und Einstellungen in Übereinstimmung mit der aktuellen Computerumgebung generiert wurde. Die Laufzeit wird auf die JIT-Kompilierung einer Assembly zurückgesetzt, falls kein geeignetes systemeigenes Abbild gefunden werden kann. Die folgenden Änderungen an den Einstellungen und der Umgebung eines Computers führen dazu, dass systemeigene Abbilder ungültig werden:

• Version von .NET Framework.

  Wenn Sie .NET Framework aktualisieren, werden alle von Ihnen mit Ngen.exe erstellten systemeigenen Abbilder ungültig. Aus diesem Grund wird bei allen Aktualisierungen von .NET Framework der Befehl Ngen Update ausgeführt, um sicherzustellen, dass alle systemeigenen Abbilder erneut generiert werden. .NET Framework erzeugt automatisch neue systemeigene Abbilder für die .NET Framework-Bibliotheken, die installiert werden.

• Die Version des Betriebssystems, wenn der Wechsel von der Windows 9x-Familie zur Windows NT-Familie durchgeführt wird.

  Wenn sich beispielsweise die Version des Betriebssystems eines Computers von Windows 98 in Windows XP ändert, werden alle systemeigenen Abbilder im Cache für systemeigene Abbilder ungültig. Wenn sich das Betriebssystem jedoch von Windows 2000 in Windows XP ändert, werden die Abbilder nicht ungültig.

• Exakte Identität der Assembly.

  Nach dem Rekompilieren einer Assembly wird das systemeigene Abbild der Assembly ungültig.

• Genaue Identität aller Assemblys, auf die die Assembly verweist.

  Wenn Sie eine verwaltete Assembly aktualisieren, werden alle systemeigenen Abbilder, die direkt oder indirekt von dieser Assembly abhängen, ungültig, und müssen erneut generiert werden. Dies betrifft sowohl normale Verweise als auch fest gebundene Abhängigkeiten. Bei jeder Softwareaktualisierung sollte das Installationsprogramm den Befehl Ngen Update ausführen, um sicherzustellen, dass alle abhängigen systemeigenen Abbilder erneut generiert werden.

• Sicherheitsfaktoren.

  Wenn die Sicherheitsrichtlinien eines Computers so geändert werden, dass Berechtigungen für eine Assembly widerrufen werden, können vorher kompilierte systemeigene Abbilder für die entsprechende Assembly ungültig werden.

  Detaillierte Informationen über die Verwaltung der Codezugriffssicherheit durch die Common Language Runtime und die Verwendung von Berechtigungen finden Sie unter Codezugriffssicherheit.

Beispiele

Durch den folgenden Befehl wird ein systemeignes Abbild für ClientApp.exe generiert, im aktuellen Verzeichnis abgelegt und anschließend im Cache für systemeigene Abbilder installiert. Wenn eine Konfigurationsdatei für die Assembly vorhanden ist, wird sie von Ngen.exe verwendet. Außerdem werden systemeigene Abbilder für alle DLL-Dateien generiert, auf die ClientApp.exe verweist.

ngen install ClientApp.exe

Ein mit Ngen.exe installiertes Abbild wird auch als Stammelement bezeichnet. Ein Stammelement kann eine Anwendung oder eine freigegebene Komponente sein.

Durch den folgenden Befehl wird ein systemeigenes Abbild für MyAssembly.exe mit dem angegebenen Pfad generiert.

ngen install c:\myfiles\MyAssembly.exe

Bei der Suche nach Assemblys und ihren Abhängigkeiten verwendet Ngen.exe dieselbe Überprüfungslogik wie die Common Language Runtime. Das Verzeichnis, in dem ClientApp.exe enthalten ist, wird standardmäßig als Basisverzeichnis der Anwendung verwendet, und sämtliche Überprüfungen von Assemblys werden in diesem Verzeichnis gestartet. Sie können dieses Verhalten mit der Option /AppBase außer Kraft setzen.

Eine Assembly kann über eine Abhängigkeit ohne Verweis verfügen, z. B. wenn sie eine DLL-Datei mithilfe der System.Reflection.Assembly.Load-Methode lädt. Sie können mit der Option /ExeConfig ein systemeigenes Abbild für eine solche DLL-Datei erstellen, indem Sie Konfigurationsinformationen für die Anwendungsassembly verwenden. Der folgende Befehl generiert ein systemeigenes Abbild für MyLib.dll,, indem er Konfigurationsinformationen aus MyApp.exe verwendet.

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

Auf diese Weise installierte Assemblys werden nicht entfernt, wenn die Anwendung entfernt wird.

Verwenden Sie zum Deinstallieren einer Abhängigkeit dieselben Befehlszeilenoptionen wie beim Installieren. Durch den folgenden Befehl wird MyLib.dll aus dem vorherigen Beispiel deinstalliert.

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

Um ein systemeigenes Abbild für eine Assembly im globalen Assemblycache zu erstellen, verwenden Sie den Anzeigenamen der Assembly. Beispiel:

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

Ngen.exe generiert einen separaten Satz von Abbildern für jedes Szenario, das Sie installieren. Durch die folgenden Befehle wird beispielsweise ein vollständiger Satz von systemeigenen Abbildern für den normalen Ablauf, ein anderer vollständiger Satz für das Debuggen und ein dritter Satz für die Profilerstellung erstellt:

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

Anzeigen des Caches für systemeigene Abbilder

Nachdem systemeigene Abbilder im Cache installiert wurden, können sie mithilfe von Ngen.exe angezeigt werden. Mit dem folgenden Befehl werden alle systemeigenen Abbilder aus dem Cache für systemeigene Abbilder angezeigt.

ngen display

Durch die Aktion display werden zuerst alle Stammassemblys und dann alle systemeigenen Abbilder auf dem Computer aufgelistet.

Verwenden Sie den einfachen Namen einer Assembly, um nur Informationen für diese Assembly anzuzeigen. Durch den folgenden Befehl werden alle systemeigenen Abbilder aus dem Cache für systemeigene Abbilder angezeigt, die den Teilnamen MyAssembly aufweisen, sowie ihre Abhängigkeiten und alle Stammassemblys, die über eine Abhängigkeit zu MyAssembly verfügen:

ngen display MyAssembly

Um den Einfluss zu beurteilen, den eine Aktion update nach der Aktualisierung der freigegebenen Komponente hat, ist es hilfreich, die Stammassemblys zu kennen, die von der Assembly der freigegebenen Komponente abhängen.

Wenn Sie die Dateierweiterung einer Assembly angeben, müssen Sie entweder den Pfad angeben oder Ngen.exe von dem Verzeichnis aus ausführen, in dem die Assembly enthalten ist:

ngen display c:\myApps\MyAssembly.exe

Der folgende Befehl dient zur Anzeige aller systemeigenen Abbilder im Cache für systemeigene Abbilder mit dem Namen MyAssembly und der Version 1.0.0.0.

ngen display "myAssembly, version=1.0.0.0"

Aktualisieren von Abbildern

Abbilder werden normalerweise aktualisiert, nachdem eine freigegebene Komponente aktualisiert wurde. Um alle systemeigenen Abbilder zu aktualisieren, die bzw. deren Abhängigkeiten geändert wurden, verwenden Sie die Aktion update ohne Argumente.

ngen update

Das Aktualisieren aller Abbilder kann ein langwieriger Prozess sein. Sie können die Aktualisierungen mit der Option /queue in eine Warteschlange einreihen, um sie vom Dienst für systemeigene Abbilder ausführen zu lassen. Weitere Informationen zur Option /queue und den Prioritäten bei der Installation finden Sie unter Dienst für systemeigene Abbilder.

ngen update /queue

Deinstallieren von Abbildern

Ngen.exe verwaltet eine Liste von Abhängigkeiten. Freigegebene Komponenten können demnach nur entfernt werden, nachdem alle Assemblys, die von diesen Komponenten abhängen, entfernt wurden. Darüber hinaus wird eine freigegebene Komponente, die als Stamm installiert wurde, nicht entfernt.

Durch den folgenden Befehl werden alle Szenarios für den Stamm ClientApp.exe deinstalliert:

ngen uninstall ClientApp

Mit der Aktion uninstall können bestimmte Szenarios entfernt werden. Durch den folgenden Befehl werden alle Debugszenarios für ClientApp.exe deinstalliert:

ngen uninstall ClientApp /debug

Durch den folgenden Befehl werden alle Szenarios für eine bestimmte Version von ClientApp.exe deinstalliert:

ngen uninstall "ClientApp, Version=1.0.0.0"

Durch die folgenden Befehle werden alle Szenarios für "ClientApp, Version=1.0.0.0, Culture=neutral, PublicKeyToken=3c7ba247adcd2081, processorArchitecture=MSIL", oder nur das Debugszenario für diese Assembly deinstalliert:

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

Wie bei der Aktion install bewirkt die Angabe einer Erweiterung, dass Ngen.exe entweder von dem Verzeichnis aus ausgeführt werden muss, in dem die Assembly enthalten ist, oder dass der vollständige Pfad angegeben werden muss.

Beispiele, die sich auf den Dienst für systemeigene Abbilder beziehen, finden Sie unter Dienst für systemeigene Abbilder.

Siehe auch

Referenz

.NET Framework-Tools
SDK-Eingabeaufforderung

Konzepte

Dienst für systemeigene Abbilder
Kompilieren von MSIL in systemeigenen Code
So sucht Common Language Runtime nach Assemblys