Legacysyntax des Native Image Generator (Ngen.exe)

Artikel
08/10/2011

Die Informationen in diesem Abschnitt richten sich an Benutzer von .NET Framework, Version 1.0 und 1.1. Die Syntax der Version 2.0 finden Sie unter Ngen.exe (Native Image Generator).

Durch den Native Image Generator wird ein systemeigenes Abbild aus einer verwalteten Assembly erstellt und im Cache für systemeigene Abbilder auf dem lokalen Computer installiert. Der Cache für systemeigene Abbilder ist ein spezieller Bereich des globalen Assemblycaches. Nachdem Sie ein systemeigenes Abbild einer Assembly erstellt haben, verwendet die Common Language Runtime bei jedem Ausführen der Assembly automatisch dieses Abbild. Es sind keine zusätzlichen Schritte erforderlich, damit die Common Language Runtime ein systemeigenes Abbild verwendet. Das Ausführen von Ngen.exe sorgt für das schnellere Laden und Ausführen von Assemblys, da Code und Datenstrukturen nicht dynamisch generiert, sondern aus dem Cache für systemeigene Abbilder wiederhergestellt werden.

ngen [options] [assemblyName |assemblyPath ]

Parameter

Argument	Beschreibungen
assemblyName	Der Name der Assembly, für die ein systemeigenes Abbild generiert wird. Die Assembly muss sich im aktuellen Verzeichnis befinden. Sie können entweder einen teilweise angegebenen Assemblynamen wie myAssembly oder einen vollständig angegebenen Assemblynamen wie myAssembly, Version=2.0.0.0, Culture=neutral, PublicKeyToken=0038abc9deabfle5 verwenden. Wenn Ngen.exe die Herausgeberrichtliniendatei einer Assembly finden und verwenden soll, müssen Sie einen vollständig spezifizierten Assemblynamen verwenden.
assemblyPath	Der explizite Pfad der Assembly, für die ein systemeigenes Abbild generiert wird. Sie können einen vollständigen Pfad zu einer Assembly wie c:\applications\myApp\myApp.exe und einen relativen Pfad angeben wie ... \applications\myApp\myApp.exe, oder ein Dateiname wie myApp.exe. Wenn Sie nur einen Dateinamen wie myApp.exe ohne einen vollständigen oder relativen Pfad verwenden, muss sich die Assembly im aktuellen Verzeichnis befinden. Damit Ngen.exe eine Assembly als ausführbare Datei identifizieren und die zugehörige Konfigurationsdatei auffinden kann, sollten Sie zum Angeben von Assemblys mit der Dateinamenerweiterung .exe das assemblyPath-Argument verwenden. Wenn Sie mehr als eine Assembly in der Befehlszeile angeben, darf nur eine der Assemblys eine ausführbare Datei sein. Mit dem Tool können Sie den anderen Assemblys die Bindungseigenschaften (Anwendungsbasis und alle Konfigurationsdateien) der ausführbaren Datei zuweisen.

assemblyName

Der Name der Assembly, für die ein systemeigenes Abbild generiert wird. Die Assembly muss sich im aktuellen Verzeichnis befinden. Sie können entweder einen teilweise angegebenen Assemblynamen wie myAssembly oder einen vollständig angegebenen Assemblynamen wie myAssembly, Version=2.0.0.0, Culture=neutral, PublicKeyToken=0038abc9deabfle5 verwenden. Wenn Ngen.exe die Herausgeberrichtliniendatei einer Assembly finden und verwenden soll, müssen Sie einen vollständig spezifizierten Assemblynamen verwenden.

assemblyPath

Der explizite Pfad der Assembly, für die ein systemeigenes Abbild generiert wird. Sie können einen vollständigen Pfad zu einer Assembly wie c:\applications\myApp\myApp.exe und einen relativen Pfad angeben wie ... \applications\myApp\myApp.exe, oder ein Dateiname wie myApp.exe.

Wenn Sie nur einen Dateinamen wie myApp.exe ohne einen vollständigen oder relativen Pfad verwenden, muss sich die Assembly im aktuellen Verzeichnis befinden.

Damit Ngen.exe eine Assembly als ausführbare Datei identifizieren und die zugehörige Konfigurationsdatei auffinden kann, sollten Sie zum Angeben von Assemblys mit der Dateinamenerweiterung .exe das assemblyPath-Argument verwenden.

Wenn Sie mehr als eine Assembly in der Befehlszeile angeben, darf nur eine der Assemblys eine ausführbare Datei sein. Mit dem Tool können Sie den anderen Assemblys die Bindungseigenschaften (Anwendungsbasis und alle Konfigurationsdateien) der ausführbaren Datei zuweisen.

Option	Beschreibungen
/debug	Generiert ein systemeigenes Abbild, das von einem Debugger im normalen Debugmodus verwendet wird.
/debugopt	Generiert ein systemeigenes Abbild, das von einem Debugger im optimierten Debugmodus von Common Language Runtime verwendet wird. Weitere Informationen zum Aktivieren dieses Modus finden Sie im Handbuch zum Debugger.
/delete [assemblyName \| assemblyPath \| *]	Löscht im Cache für systemeigene Abbilder die systemeigenen Abbilder für den angegebenen assemblyName oder assemblyPath. Mit dem ''-Parameter werden alle systemeigenen Abbilder im Abbildcache gelöscht. Wenn Sie für die Option /delete* keinen Parameter angeben, zeigt das Tool eine Fehlermeldung an. Wenn Sie einer Version von .NET Framework deinstallieren, werden mithilfe der Option /delete während des Deinstallationsvorgangs allen systemeigenen Abbilder der entsprechenden .NET Framework-Version gelöscht. Dies umfasst sowohl systemeigene Abbilder, die bei der Installation für .NET Framework-Assemblys erstellt wurden, als auch alle systemeigenen Abbilder, die von Benutzern für benutzerdefinierte Assemblys erstellt wurden. Wenn Sie für die Option /delete * die Option /show angeben, zeigt das Tool eine Liste aller gelöschten systemeigenen Abbilder an. Zum Löschen von systemeigenen Abbildern auf einem Computer, auf dem mehrere Versionen von .NET Framework installiert sind, muss dieselbe Version von Ngen.exe verwendet werden wie zum Erstellen des systemeigenen Abbildes. Hinweis Diese Option wirkt sich nur auf die mit "Ngen.exe" generierten systemeigenen Images aus.Dies hat keine Auswirkungen auf die tatsächlichen Assemblys.
/help	Zeigt Befehlssyntax und Optionen für das Tool an.
/nologo	Unterdrückt die Anzeige des Startbanners von Microsoft.
/prof	Generiert ein systemeigenes Abbild, das von einem Profiler mit instrumentalisiertem Code verwendet wird. Weitere Informationen darüber, ob instrumentalisierter Code für den Profiler benötigt wird, finden Sie in der Dokumentation zum Profiler.
/show	Zeigt die im Cache für systemeigene Abbilder vorhandenen Dateien für den angegebenen assemblyName oder assemblyPath an. Wenn Sie keine Argumente angeben, wird der gesamte Inhalt des Caches für systemeigene Abbilder angezeigt. Mit dieser Option werden Assemblydefinitionsdaten für die Quellassembly angezeigt sowie alle besonderen Codekonfigurationsoptionen für jedes systemeigene Abbild. Wenn Sie die Option /delete * für diese Option angeben, zeigt das Tool eine Liste aller gelöschten systemeigenen Abbilder an.
/showversion	Zeigt die Version der Common Language Runtime an, die von Ngen.exe zum Erzeugen eines systemeigenen Abbildes für die angegebene Assembly verwendet wird. Verwenden Sie diese Option, um festzustellen, welche Version von .NET Framework das Tool auf einem Computer verwendet, auf dem mehrere Versionen installiert sind. Weitere Informationen über das Ausführen mehrerer Versionen der Common Language Runtime finden Sie unter Verwenden der parallelen Ausführung. Hinweis Mit dieser Option wird kein systemeigenes Abbild generiert.
/silent	Unterdrückt die Anzeige von Erfolgsmeldungen.
/?	Zeigt Befehlssyntax und Optionen für das Tool an.

Hinweise

Für die Suche nach den von Ihnen in der Befehlszeile angegebenen Assemblys verwendet Ngen.exe keine Standardüberprüfungsregeln für Assemblys. Ngen.exe durchsucht nur das aktuelle Verzeichnis nach den von Ihnen angegebenen Assemblys. Damit die Assemblys von Ngen.exe gefunden werden können, sollten Sie daher entweder als Arbeitsverzeichnis das Verzeichnis festlegen, das die Assemblys enthält, für die systemeigene Abbilder erstellt werden sollen, oder den exakten Pfad zu den Assemblys angeben.

Ein systemeigenes Abbild ist eine Datei, die kompilierten prozessorspezifischen Computercode enthält. Beachten Sie, dass mit Ngen.exe erzeugte systemeigene Abbilder nicht für andere Anwendungsdomänen freigegeben werden können. Deshalb kann Ngen.exe nicht in Anwendungsszenarios verwendet werden, in denen Assemblys von mehreren Anwendungsdomänen gemeinsam genutzt werden.

Das Vorkompilieren von Assemblys mit Ngen.exe kann die Startgeschwindigkeit von Anwendungen erhöhen, da dadurch ein Großteil des Codes bereits im Voraus ausgeführt wird. Aus diesem Grund eignet sich "Ngen.exe" besser für Anwendungen auf der Clientseite, wo die von der JIT (Just-in-Time)-Kompilierung in Anspruch genommenen CPU-Zyklen die Geschwindigkeit beeinträchtigen.

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

Da es viele Faktoren gibt, die sich auf die Startzeit einer Anwendung auswirken, sollten Sie sorgfältig bestimmen, welche Anwendungen von der Verwendung von Ngen.exe profitieren würden. Experimentieren Sie, indem Sie eine JIT-kompilierte und eine vorkompilierte Version einer Kandidatenassembly in der Umgebung ausführen, in der sie verwendet wird. Auf diese Weise können Sie die Ausführung einer Assembly unter verschiedenen Kompilierungsschemas ausprobieren und die jeweiligen Startgeschwindigkeiten vergleichen.

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. Wenn Sie eine Assembly z. B. in einem Debug- oder Profilerszenario ausführen, sucht die Common Language Runtime nach einem systemeigenen Abbild, das mit den Optionen /debug, /debugopt oder /prof erstellt wurde. Wenn kein entsprechendes systemeigenes Abbild gefunden wurde, wird die Laufzeit auf die standardmäßige JIT-Kompilierung zurückgesetzt.

Wenn Sie Ngen.exe auf einer Assembly mit einem debugfähigen Codeattribut ausführen, wird abhängig von den Flags des Attributs der Code automatisch so generiert, als ob die Optionen /debug oder /debugopt angegeben wären.

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. Führt Common Language Runtime diese Assembly aus, werden die nicht im systemeigenen Abbild enthaltenen Methoden auf JIT-Kompilierung zurückgesetzt.

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

Version von .NET Framework.
CPU-Typ.
Version des Betriebssystems.
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 Common Language Runtime 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 ein Update für .NET Framework anwenden, werden alle von Ihnen mit Ngen.exe manuell erstellten systemeigenen Abbilder ungültig. Die Assemblys können zwar noch immer ausgeführt werden, aber die Common Language Runtime kann die entsprechenden systemeigenen Abbilder der Assemblys nicht mehr laden. Für diese Assemblys müssen manuell neue systemeigene Abbilder erstellt werden.

.NET Framework erzeugt automatisch neue systemeigene Abbilder für die .NET Framework-Bibliotheken, die installiert werden.
CPU-Typ.

Wenn Sie den Prozessor eines Computers auf eine neue Prozessorfamilie aktualisieren, werden alle systemeigenen Abbilder im systemeigenen Abbildcache ungültig.
Version des Betriebssystems.

Wenn die Version des Betriebssystems eines Computers sich ändert, werden alle systemeigenen Abbilder im systemeigenen Abbildcache 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.

Nach dem Rekompilieren einer Assembly, auf die eine Assembly verweist, wird das entsprechende systemeigene Abbild der Assembly ungültig.

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. Insbesondere das Widerrufen einer der folgenden Berechtigungen kann zum Ungültigwerden des gegenwärtigen systemeigenen Abbildes einer Assembly führen:

Eine deklarative Vererbungsberechtigung, die von einer Klasse gefordert wird, von der die Assembly abgeleitet ist.
Eine deklarative Verknüpfungszeitberechtigung, die von einer von der Assembly aufgerufenen Methode gefordert wird.
SkipVerification-Berechtigung, wenn die Assembly nicht überprüfbare Methoden beinhaltet. Weitere Informationen über diese Berechtigung finden Sie unter SecurityPermissionAttribute.SkipVerification Property.
UnmanagedCode-Berechtigung, wenn die Assembly PInvoke-Aufrufe ausführt. Weitere Informationen über diese Berechtigung finden Sie unter SecurityPermissionAttribute.UnmanagedCode Property.

Wenn Sie Ngen.exe für eine Assembly mit deaktivierter Codezugriffssicherheit ausführen, wird das erzeugte systemeigene Abbild ungültig, wenn die Codezugriffssicherheit aktiviert wird. Die Codezugriffssicherheit ist in der Standardeinstellung aktiviert.

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

Hinweis
In der Version 1.0 der Common Language Runtime können ungültige systemeigene Abbilder nicht automatisch erstellt oder gelöscht werden.Alle systemeigenen Abbilder müssen mit Ngen.exe manuell erstellt bzw. gelöscht werden.

Wenn Sie mit Ngen.exe systemeigene Abbilder für eine Anwendung während der Installation erstellen, müssen Sie den Anwendungsdateinamen und die vollständig spezifizierten Assemblynamen der DLL-Dateien angeben, auf die die Anwendung während der Kompilierung verwiesen hat. Bei Bereitstellung der vollständig spezifizierten Namen der DLLs, auf die eine Anwendung verweist, kann Ngen.exe auf die Herausgeberrichtliniendateien für die Assemblys zugreifen, auf die verwiesen wird. In der Zukunft werden dann von Ngen.exe die Herausgeberrichtlinien angewendet, wenn DLLs aktualisiert und die Richtlinien für eine Versionsumleitung verwendet werden.

Sie können die zu verwendenden vollständig spezifizierten Assemblynamen abrufen, indem Sie Ildasm.exe für die betreffende Anwendung ausführen und sich das Assemblymanifest anzeigen lassen. Das Manifest enthält den Assemblynamen, die Version, die Kultur und das Token des öffentlichen Schlüssels für die DLLs, auf die die Anwendung während der Kompilierung verwiesen hat. Wenn Sie beispielsweise ein systemeigenes Abbild für eine Anwendung mit dem Namen ClientApp.exe erstellen möchten, die mit myLibrary.dll, Version 1.0.0.0, culture=neutral und PublicKeyToken=0038abc9deabfle5 kompiliert wurde, verwenden Sie hierzu den Befehl ngen ClientApp.exe "myLibrary, Version=1.0.0.0, Culture=neutral, PublicKeyToken=0038abc9deabfle5".

Das oben angegebene Beispiel erzeugt keine systemeigenen Abbilder für die Assemblys, auf die myLibrary.dll verweist. Um die vollständig angegebenen Namen der Assemblys zu bestimmen, auf die "myLibrary.dl" verweist, führen Sie "Ildasm.exe" für "myLibrary.dl" aus. Wenn Sie z. B. "Ildasm.exe" auf "myLibrary.dll" ausführen und bestimmen, dass es auf "myMath.dll", Version 1.0.0.0, culture=neutral und PublicKeyToken=0039def8abcbste7 verweist, verwenden Sie den folgenden Befehl, um systemeigene Abbilder für die ganze Struktur von Assemblyverweisen von "ClientApp.exe" zu generieren.

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

Weitere Informationen über dieses Format finden Sie im Abschnitt "Beispiele" weiter unten in diesem Thema.

Beim Deinstallationsvorgang für eine Anwendung sollte der /delete-Vorgang verwendet werden [assemblyName ]| assemblyPath] Option, um die systemeigenen Images zu entfernen, die zur Zeit der Anwendungsinstallation erstellt wurden. Das zu löschende systemeigene Abbild muss dabei im assemblyName-Parameter oder im assemblyPath-Parameter angegeben werden. Wenn /delete * angegeben wird, werden alle systemeigenen Abbilder im Abbildcache gelöscht. Wird die Option /delete ohne Parameter angegeben, tritt ein Fehler auf.

Beispiele

Der folgende Befehl erzeugt ein systemeigenes Abbild von ClientApp.exe, die Datei im aktuellen Verzeichnis. Wenn eine Konfigurationsdatei für die Anwendung vorhanden ist, wird sie von Ngen.exe verwendet. Das Tool erzeugt keine systemeigenen Abbilder für DLLs, auf die ClientApp.exe verweist.

ngen ClientApp.exe

Wenn ClientApp.exe direkte Verweise auf zwei DLLs, myLibOne.dll und myLibTwo.dll, beinhaltet, müssen Ngen.exe die vollständig spezifizierten Assemblynamen dieser DLLs bereitgestellt werden, damit systemeigene Abbilder für sie erzeugt werden können. Führen Sie Ildasm.exe für ClientApp.exe aus, um die vollständig spezifizierten Assemblynamen der DLLs zu ermitteln, auf die verwiesen wird. In diesem Beispiel wird davon ausgegangen, dass die vollständig spezifizierten Assemblynamen von myLibOne.dll und myLibTwo.dll wie folgt lauten: "myLibOne, Version=1.0.0.0, Culture=neutral, PublicKeyToken=0038abc9deabfle5" und "myLibTwo, Version=1.0.0.0, Culture=neutral, PublicKeyToken=0038abc9deabfle5". Mithilfe dieser Informationen erzeugt der folgende Befehl systemeigene Abbilder für ClientApp.exe, myLibOne.dll und myLibTwo.dll. Wenn eine Konfigurationsdatei für ClientApp.exe vorhanden ist, wird sie von Ngen.exe verwendet. Bestehende Herausgeberrichtliniendateien für myLibOne.dll oder myLibTwo.dll werden von Ngen.exe verwendet.

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

Die DLLs myLibOne.dll und myLibTwo.dll aus dem oben angegebenen Beispiel können ggf. auf weitere Assemblys verweisen. Führen Sie Ildasm.exe für myLibOne.dll und für myLibTwo.dll aus, um die vollständig spezifizierten Assemblynamen der Assemblys zu ermitteln, auf die verwiesen wird. In diesem Beispiel wird davon ausgegangen, dass myLibOne.dll keinen Verweis auf andere Assemblys enthält, während myLibTwo.dll auf "myMath, Version=1.0.0.0, Culture=neutral, PublicKeyToken=0039def8abcbste7" verweist. Mithilfe dieser Informationen erzeugt der folgende Befehl systemeigene Abbilder für die gesamte Baumstruktur der Assemblyverweise der Anwendung.

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"

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

ngen c:\myfiles\myAssembly.exe

Durch den folgenden Befehl wird ein systemeigenes Abbild für myLibrary.dll, mit dem angegebenen Pfad generiert.

ngen c:\myfiles\myLibrary.dll

Der Abbildcache wird von Ngen.exe durchsucht, um eine Assembly zu löschen, die mit einem teilweise spezifizierten Assemblynamen angegeben wurde. Der folgende Befehlt löscht alle systemeigenen Abbilder mit dem Namen myAssembly.

ngen /delete myAssembly

Der folgende Befehl löscht das systemeigene Abbild myAssembly mit dem vollständig angegebenen Assemblynamen.

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

Der folgende Befehl dient zur Anzeige aller systemeigenen Abbilder im Cache für systemeigene Abbilder.

ngen /show

Der folgende Befehl dient zur Anzeige aller systemeigenen Abbilder im Abbildcache mit dem Namen myAssembly.

ngen /show myAssembly

Mit dem folgenden Befehl werden alle systemeigenen Abbilder im Cache für systemeigene Abbilder mit dem Namen myAssembly und der Version 1.0 angezeigt.

ngen /show "myAssembly, version=1.0.0.0"

Siehe auch

Legacysyntax des Native Image Generator (Ngen.exe)

Parameter

Hinweise

Beispiele

Siehe auch

Referenz

Konzepte

Weitere Ressourcen

Zusätzliche Ressourcen