.NET Framework 工具 - 本机映像生成器 (Ngen.exe)

本机映像生成器创建托管程序集的本机映像，并且将该映像安装到本地计算机的本机映像缓存中。本机映像缓存是全局程序集缓存的保留区域。一旦您为某个程序集创建了本机映像，运行库在每次运行该程序集时就会自动使用该本机映像。不必执行任何其他的过程就可使运行库使用本机映像。在程序集上运行 Ngen.exe 可以提高程序集的加载和执行速度，原因是它可以从本机映像缓存中还原代码和数据结构，而不是动态生成它们。

ngen [options] [assemblyName |assemblyPath ]

参数	说明
assemblyName	为其生成本机映像的程序集的名称。程序集必须位于当前目录中。可以提供部分指定的程序集名称（如 myAssembly ）或完全指定的程序集名称（如 myAssembly, Version=2.0.0.0, Culture=neutral, PublicKeyToken=0038abc9deabfle5 ）。如果希望 Ngen.exe 找到并使用程序集的发行者策略文件，必须使用完全指定的程序集名称。
assemblyPath	为其生成本机映像的程序集的显式路径。可以指定程序集的完全路径（如 c:/applications/myApp/myApp.exe ）、相对路径（如 ../ applications/myApp/myApp.exe ）或文件名（如 myApp.exe ）。 如果指定文件名（如 myApp.exe ）而不指定完全或相对路径，则程序集必须位于当前目录中。 若要使 Ngen.exe 可以将程序集识别为可执行文件并且可以找到它的配置文件，应该使用 assemblyPath 参数指定带 .exe 扩展名的程序集。 如果在命令行上指定一个以上的程序集，则其中只能有一个是可执行文件。该工具将可执行文件的绑定属性（应用程序基础和任何配置文件）应用到您指定的其他程序集。

选项	说明
/debug	生成将由调试器在正常调试模式下使用的本机映像。
/debugopt	生成将由调试器在公共语言运行库的优化调试模式下使用的本机映像。有关如何激活此模式的详细信息，请参见您的调试器文档。
/delete [assemblyName | assemblyPath | *]	删除本机映像缓存中指定的 assemblyName 或 assemblyPath 的本机映像。如果指定“*”参数，则该工具将删除本机映像缓存中的所有本机映像。如果使用 /delete 选项而不指定参数，该工具将显示错误信息。 当卸载某个 .NET Framework 版本时，卸载进程使用 /delete 选项删除所卸载的 .NET Framework 版本的所有本机映像。这包括安装时为 .NET Framework 程序集创建的本机映像，以及用户为自定义程序集创建的任何本机映像。如果同时指定 /show 选项和 /delete * 选项，则该工具会显示它删除的本机映像的列表。 当在同一台计算机上同时安装了多个 .NET Framework 版本时，必须使用创建本机映像时所使用的同一 Ngen.exe 版本，才能删除该本机映像。 注意 此选项只影响由 Ngen.exe 生成的本机映像，它不影响实际的程序集。
/help	显示该工具的命令语法和选项。
/nologo	取消显示 Microsoft 启动标题。
/prof	生成将由使用规范的代码的分析器使用的本机映像。请参见您的分析器文档，以确定您的分析器是否要求规范的代码。
/show	为指定的 assemblyName 或 assemblyPath 显示本机映像缓存中现有的文件。如果您没有指定参数，该工具将显示本机映像缓存中的全部内容。此选项显示源程序集的程序集定义信息以及每一本机映像的任何特殊代码配置选项。 如果与 /delete * 选项一起指定此选项，则该工具会显示它删除的本机映像的列表。
/showversion	显示 Ngen.exe 生成指定程序集的本机映像所使用的运行库版本。当在同一台计算机上同时安装了多个 .NET Framework 版本时，使用此选项可以确定该工具将使用的版本。有关运行多个运行库版本的更多信息，请参见并行 (Side-by-Side) 执行。 注意 此选项不生成本机映像。
/silent	取消显示成功消息。
/?	显示该工具的命令语法和选项。

备注

Ngen.exe 不使用标准程序集探测规则来定位您在命令行上指定的程序集。Ngen.exe 只在当前目录中查找您指定的程序集。因此，要使 Ngen.exe 可以找到程序集，应该将工作目录设置为要为其创建本机映像的程序集所在的目录，或者指定程序集的确切路径。

本机映像是包含已编译的处理器特定的机器码的文件。注意，Ngen.exe 生成的本机映像不能在应用程序域之间共享。因此，在要求在应用程序域之间共享程序集的应用程序方案（如 ASP.NET）中不能使用 Ngen.exe。

通过 Ngen.exe 预编译程序集可以减少应用程序的启动时间，因为执行代码所需的大量工作已事先完成。因此，如果您已确定导致性能降低的原因在于客户端应用程序中 JIT 编译所消耗的 CPU 周期，最好将 Ngen.exe 用于客户端应用程序。

因为有许多因素都会影响应用程序的启动时间，所以应仔细判断哪些应用程序将从使用 Ngen.exe 中受益。为此，应进行以下试验：在将使用候选程序集的环境中运行该程序集的 JIT 编译版本和预编译版本。这将使您可以比较在不同的编译方案下，执行同一个程序集的启动时间。

注意 若要运行 Ngen.exe，您必须具有管理员特权。
在您生成一个程序集的本机映像后，每当运行库运行该程序集时，都会自动尝试找到并使用该本机映像。例如，如果您在调试或分析方案中运行程序集，运行库将查找由 /debug、/debugopt 或 /prof 选项生成的本机映像。如果运行库无法找到匹配的本机映像，它将恢复为标准的 JIT 编译。

如果您在具有可调试代码属性的程序集上运行 Ngen.exe，根据该属性的标志，该工具会自动生成代码，就像已经指定了 /debug 或 /debugopt 选项一样。

如果 Ngen.exe 在程序集中遇到它无法生成的任何方法，则它会将这些方法从本机映像中排除。当运行库执行此程序集时，对于那些不包括在本机映像中的方法，它将回转到 JIT 编译。

当您使用 Ngen.exe 来创建程序集的本机映像时，输出取决于您指定的命令行选项以及计算机上的某些设置。这些设置包括：

.NET Framework 的版本。

CPU 类型。

操作系统的版本。

程序集的确切标识（重新编译将更改标识）。

程序集引用的所有程序集的确切标识（重新编译将更改标识）。

安全因素。

Ngen.exe 在生成本机映像时记录这些信息。当您执行程序集时，运行库将查找用匹配计算机的当前环境的选项和设置生成的本机映像。如果运行库没有找到匹配的本机映像，它将恢复为程序集的 JIT 编译。对计算机的设置和环境进行以下更改会导致本机映像失效：

.NET Framework 的版本。
如果将修补程序、QFE 或更新应用于 .NET Framework，则使用 Ngen.exe 手动创建的所有本机映像都将失效。这些程序集仍可以运行，但运行库不会加载程序集的相应本机映像。您必须为这些程序集手动创建新的本机映像。

.NET Framework 为它安装的 .NET Framework 库自动创建新的本机映像。

CPU 类型。
如果将计算机的处理器升级到新的处理器系列，则存储在本机映像缓存中的所有本机映像都将失效。

操作系统的版本。
如果计算机上运行的操作系统的版本发生更改，则存储在本机映像缓存中的所有本机映像都将失效。

程序集的确切标识。
如果重新编译程序集，则程序集的相应本机映像将失效。

程序集引用的任何程序集的确切标识。
如果重新编译某个程序集引用的任何程序集，则该程序集的相应本机映像将失效。

安全因素。
更改计算机安全策略以限制先前授予某个程序集的权限，这样会导致该程序集的先前编译的本机映像失效。具体说来，撤消下列任何权限都会导致程序集的当前本机映像失效：

派生程序集的类所要求的声明性继承权限。

程序集调用的方法所要求的声明性链接时权限。

SkipVerification 权限（如果程序集包含任何无法验证的方法）。有关此权限的更多信息，请参见 SecurityPermissionAttribute.SkipVerification 属性。

UnmanagedCode 权限（如果程序集进行任何 PInvoke 调用）。有关此权限的更多信息，请参见 SecurityPermissionAttribute.UnmanagedCode 属性。

如果在关闭了代码访问安全的程序集上运行 Ngen.exe，则它生成的本机映像将在打开代码访问安全时失效。注意，默认情况下，代码访问安全是打开的。

有关公共语言运行库如何管理代码访问安全以及如何使用权限的详细信息，请参见代码访问安全性

注意 在公共语言运行库 1.0 版中，不自动创建或删除失效的本机映像。您必须使用 Ngen.exe 手动创建或删除所有本机映像。

如果使用 Ngen.exe 在安装时生成应用程序的本机映像，必须指定应用程序的文件名，以及应用程序在编译时引用的 .dll 文件的完全指定程序集名称。提供应用程序引用的 DLL 文件的完全指定程序集名称，可使 Ngen.exe 能够访问所引用的程序集的发行者策略文件。将来，如果更新 DLL 文件并使用发行者策略重定向版本，Ngen.exe 将应用发行者策略。

通过在应用程序上运行 Ildasm.exe 并查看其程序集清单，可以获得要使用的完全指定程序集名称。该清单显示了应用程序在编译时引用的 DLL 文件的程序集名称、版本、区域性和公钥标记。例如，如果想为一个名为 ClientApp.exe 的应用程序创建本机映像，而该应用程序是用版本为 1.0.0.0、区域性为非特定语言、公钥标记为 0038abc9deabfle5 的 myLibrary.dll 文件编译的，则请使用命令

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

。

注意，前面的示例不会生成 myLibrary.dll 引用的程序集的本机映像。若要确定 myLibrary.dll 引用的程序集的完全指定名称，请在 myLibrary.dll 上运行 Ildasm.exe。例如，如果您在 myLibrary.dll 上运行 Ildasm.exe，并确定它引用版本为 1.0.0.0、区域性为非特定语言、公钥标记为 0039def8abcbste7 的 myMath.dll，请使用下面的命令为 ClientApp.exe 的整个程序集引用目录树生成本机映像。

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

有关此格式的更多信息，请参见本主题后面的“示例”一节。

应用程序的卸载进程应该使用 /delete [assemblyName | assemblyPath] 选项来移除安装应用程序时创建的本机映像。必须使用 assemblyName 或 assemblyPath 参数指定要删除的特定本机映像。指定 /delete * 将移除本机映像缓存中的所有本机映像；指定 /delete 选项而不指定参数将产生错误。

示例

下面的命令为当前目录中的

ClientApp.exe

生成本机映像。如果该应用程序存在配置文件，Ngen.exe 将使用它。该工具不会为

ClientApp.exe

引用的任何 DLL 生成本机映像。

ngen ClientApp.exe

如果

ClientApp.exe

直接引用两个 DLL（

myLibOne.dll

和

myLibTwo.dll

），则必须为 Ngen.exe 提供这些 DLL 的完全指定程序集名称，才能为它们生成本机映像。对

ClientApp.exe

运行 Ildasm.exe，确定所引用的 DLL 的完全指定程序集名称。在此示例中，

myLibOne.dll

和

myLibTwo.dll

的完全指定程序集名称是

"myLibOne, Version=1.0.0.0, Culture=neutral, PublicKeyToken=0038abc9deabfle5"

和

"myLibTwo, Version=1.0.0.0, Culture=neutral, PublicKeyToken=0038abc9deabfle5"

。使用此信息，下面的命令生成

ClientApp.exe

、

myLibOne.dll

和

myLibTwo.dll

的本机映像。如果

ClientApp.exe

存在配置文件，则 Ngen.exe 将使用它。如果

myLibOne.dll

或

myLibTwo.dll

存在发行者策略文件，则 Ngen.exe 将使用它。

ngen ClientApp.exe "myLibOne[code], Version=1.0.0.0, Culture=neutral, PublicKeyToken=0038abc9deabfle5

", "myLibTwo

, Version=1.0.0.0, Culture=neutral, PublicKeyToken=0038abc9deabfle5

"[/code]
在上例中，DLL 文件

myLibOne.dll

和

myLibTwo.dll

可以引用其他程序集。若要确定所引用的程序集的完全指定程序集名称，请在

myLibOne.dll

和

myLibTwo.dll

上运行 Ildasm.exe。在此示例中，假设

myLibOne.dll

没有引用任何其他程序集，

myLibTwo.dll

引用

"myMath, Version=1.0.0.0, Culture=neutral, PublicKeyToken=0039def8abcbste7"

。使用此信息，下面的命令为应用程序的整个程序集引用目录树生成本机映像。

ngen ClientApp.exe "myLibOne[code], 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

"[/code]
下面的命令生成具有指定路径的

myAssembly.exe

的本机映像。

ngen c:/myfiles/myAssembly.exe

下面的命令按照指定路径生成 myLibrary.dll 的本机映像。

ngen c:/myfiles/myLibrary.dll

Ngen.exe 在本机映像缓存中查找，删除用部分程序集名称指定的程序集。下面的命令删除具有

myAssembly

名称的所有本机映像。

ngen /delete myAssembly

下面的命令删除具有完全指定程序集名称的本机映像

myAssembly

。

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

下面的命令显示本机映像缓存中的所有本机映像。

ngen /show

下面的命令显示本机映像缓存中名为

myAssembly

的所有本机映像。

ngen /show myAssembly

下面的命令显示本机映像缓存中名为

myAssembly

、版本为 1.0 的所有本机映像。

ngen /show "myAssembly, version=1.0.0.0"