本机映像生成器 (Ngen.exe) 旧式语法

本主题中的信息是为 .NET Framework 1.0 和 1.1 版用户提供的。 对于 2.0 版语法，请参见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 生成的本机映像不能在应用程序域之间共享。 因此，对于要求在应用程序域之间共享程序集的应用程序方案，不能使用 Ngen.exe。

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

注意
若要运行 Ngen.exe，您必须具有管理特权。

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

在您生成一个程序集的本机映像后，每当运行时运行该程序集时，都会自动尝试找到并使用该本机映像。 例如，如果您在调试或分析方案中运行程序集，运行时将查找由 /debug、/debugopt 或 /prof 选项生成的本机映像。 如果运行时无法找到匹配的本机映像，它将恢复为标准的 JIT 编译。

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

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

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

• .NET Framework 的版本。

• CPU 类型。

• 操作系统的版本。

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

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

• 安全因素。

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

• .NET Framework 的版本。

  如果将更新应用于 .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 引用的程序集的完全指定名称，请在 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, Version=1.0.0.0, Culture=neutral, PublicKeyToken=0038abc9deabfle5", "myLibTwo, Version=1.0.0.0, Culture=neutral, PublicKeyToken=0038abc9deabfle5"

在上例中，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, 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"

下面的命令生成具有指定路径的 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"

请参见

参考

Visual Studio 和 Windows SDK 命令提示

概念

托管执行过程

运行时如何定位程序集

其他资源

.NET Framework 工具