Ngen.exe （本机映像生成器）

本机映像生成器（Ngen.exe）是一种提高托管应用程序性能的工具。 Ngen.exe 创建本机映像，这些文件包含编译的特定于处理器的计算机代码，并将其安装到本地计算机上的本机映像缓存中。 运行时可以使用缓存中的本机映像，而不是使用实时 （JIT） 编译器来编译原始程序集。

对 .NET Framework 4 中 Ngen.exe 的更改：

• Ngen.exe 现在编译完全信任的程序集，并且不再评估代码访问安全性 （CAS） 策略。

• 使用 Ngen.exe 生成的本机映像无法再加载到部分信任中运行的应用程序。

对 .NET Framework 版本 2.0 中 Ngen.exe 的更改：

• 安装程序集还会安装其依赖项，从而简化 Ngen.exe的语法。

• 本机映像现在可以跨应用程序域共享。

• 一个新作 update，重新创建已失效的映像。

• 作可由在计算机上使用空闲时间生成和安装映像的服务延迟执行。

• 已消除图像失效的一些原因。

在 Windows 8 上，请参阅 本机映像任务。

有关使用 Ngen.exe 和本机映像服务的其他信息，请参阅 本机映像服务。

此工具会自动随 Visual Studio 一起安装。 若要运行该工具，请使用 Visual Studio 开发人员命令提示或 Visual Studio 开发人员 PowerShell。

在命令提示符处，键入以下内容：

Syntax

ngen action [options]

ngen /? | /help

行动

下表显示了每个 action项的语法。 有关单个action部分的说明，请参阅参数、优先级、方案和配置表。 “选项”表描述了options帮助开关和帮助开关。

Arguments

优先级级别

Scenarios

Config

选项

注解

若要运行 Ngen.exe，必须具有管理权限。

从 .NET Framework 4 开始，使用 Ngen.exe 生成的本机映像无法再加载到在部分信任中运行的应用程序。 而是调用实时 （JIT） 编译器。

Ngen.exe 为作及其所有依赖项的参数指定的assemblynameinstall程序集生成本机映像。 依赖项由程序集清单中的引用确定。 唯一需要单独安装依赖项的方案是应用程序使用反射加载依赖项时，例如通过调用 Assembly.Load 该方法。

Ngen.exe 维护依赖项计数。 例如，假设 MyAssembly.exe 和 YourAssembly.exe 都安装在本机映像缓存中，并且两者都具有对的引用 OurDependency.dll。 如果 MyAssembly.exe 卸载， OurDependency.dll 则不会卸载。 仅当同时卸载时 YourAssembly.exe ，才会将其删除。

如果要为全局程序集缓存中的程序集生成本机映像，请指定其显示名称。 请参阅 Assembly.FullName。

Ngen.exe 生成的本机映像可以跨应用程序域共享。 这意味着可以在需要跨应用程序域共享程序集的应用程序方案中使用 Ngen.exe。 若要指定域中立性，请：

• 将 LoaderOptimizationAttribute 属性应用于应用程序。

• AppDomainSetup.LoaderOptimization为新应用程序域创建设置信息时设置属性。

将同一程序集加载到多个应用程序域中时，始终使用非特定域代码。 如果本机映像在加载到共享域后被加载到非共享应用程序域中，则无法使用它。

在此“备注”部分中：

• 为不同方案生成映像

• 确定何时使用本机映像

  • 改进了内存使用

  • 更快的应用程序启动

  • 使用情况注意事项摘要

• 程序集基址的重要性

• 硬绑定

  • 指定依赖项的绑定提示

  • 指定程序集的默认绑定提示

• 延迟处理

• 本机映像和 JIT 编译

  • 无效图像

• 故障排除

  • 程序集绑定日志查看器

  • JITCompilationStart 托管调试助手

  • 选择退出本机映像生成

为不同方案生成映像

为程序集生成本机映像后，运行时会在每次运行程序集时自动尝试查找和使用此本机映像。 可以根据使用方案生成多个映像。

例如，如果在调试或分析方案中运行程序集，运行时将查找使用 /Debug 或 /Profile 选项生成的本机映像。 如果找不到匹配的本机映像，运行时将还原为标准 JIT 编译。 调试本机映像的唯一方法是使用 /Debug 此选项创建本机映像。

该 uninstall 作还识别方案，因此可以卸载所有方案或仅选择的方案。

确定何时使用本机映像

本机映像可以在两个方面提供性能改进：内存使用率改进和启动时间缩短。

改进了内存使用

在进程之间共享代码时，本机映像可以显著提高内存使用。 本机映像是 Windows PE 文件，因此多个进程可以共享 .dll 文件的单个副本;相比之下，JIT 编译器生成的本机代码存储在专用内存中，不能共享。

在终端服务下运行的应用程序也可以受益于共享代码页。

此外，不加载 JIT 编译器会为每个应用程序实例节省固定的内存量。

更快的应用程序启动

使用 Ngen.exe 预编译程序集可以提高某些应用程序的启动时间。 通常，当应用程序共享组件程序集时，可能会获得收益，因为在启动第一个应用程序后，已为后续应用程序加载共享组件。 冷启动（应用程序中的所有程序集都必须从硬盘加载）不会从本机映像中受益，因为硬盘访问时间占主导地位。

硬绑定可能会影响启动时间，因为必须同时加载硬绑定到主应用程序程序集的所有映像。

使用情况注意事项摘要

以下一般注意事项和应用程序注意事项可能有助于决定是否为应用程序评估本机映像：

• 本机映像的加载速度比 CIL 快，因为它们无需执行许多启动活动，例如 JIT 编译和类型安全验证。

• 本机映像需要较小的初始工作集，因为不需要 JIT 编译器。

• 本机映像支持进程之间的代码共享。

• 本机映像需要比 CIL 程序集更多的硬盘空间，并且可能需要相当长的时间才能生成。

• 必须维护本机映像。

  • 在为原始程序集或其依赖项之一提供服务时，需要重新生成映像。

  • 单个程序集可能需要多个本机映像才能在不同的应用程序或不同的方案中使用。 例如，两个应用程序中的配置信息可能会导致同一依赖程序集的不同绑定决策。

  • 本机映像必须由管理员生成;也就是说，来自管理员组中的 Windows 帐户。

除了这些一般注意事项外，在确定本机映像是否可提供性能优势时，必须考虑应用程序的性质：

• 如果应用程序在使用多个共享组件的环境中运行，则本机映像允许多个进程共享这些组件。

• 如果应用程序使用多个应用程序域，则本机映像允许跨域共享代码页。

  注释

  在 .NET Framework 版本 1.0 和 1.1 中，无法跨应用程序域共享本机映像。 在版本 2.0 或更高版本中，情况并非如此。

• 如果应用程序将在终端服务器下运行，本机映像允许共享代码页。

• 大型应用程序通常受益于编译到本机映像。 小型应用程序通常不会受益。

• 对于长时间运行的应用程序，运行时 JIT 编译的性能略高于本机映像。 （硬绑定可以在某种程度上缓解这种性能差异。

程序集基址的重要性

由于本机映像是 Windows PE 文件，因此它们受到与其他可执行文件相同的重包问题。 如果采用硬绑定，则重新定位的性能成本更加明显。

若要设置本机映像的基址，请使用编译器的相应选项设置程序集的基址。 Ngen.exe 将此基址用于本机映像。

可以使用 dumpbin.exe 等工具查看本机映像的首选基址。

硬绑定

硬绑定会增加吞吐量，并减少本机映像的工作集大小。 硬绑定的缺点是，加载程序集时必须加载硬绑定到程序集的所有映像。 这可以显著增加大型应用程序的启动时间。

硬绑定适用于在所有应用程序的性能关键方案中加载的依赖项。 与本机映像使用的任何方面一样，仔细的性能度量是确定硬绑定是否提高应用程序性能的唯一方法。

使用 DependencyAttribute 和 DefaultDependencyAttribute 属性，可以为 Ngen.exe提供硬绑定提示。

指定依赖项的绑定提示

DependencyAttribute向程序集应用以指示加载指定依赖项的可能性。 LoadHint.Always 指示硬绑定合适， Default 指示应使用依赖项的默认值，并 Sometimes 指示硬绑定不适用。

以下代码显示了具有两个依赖项的程序集的属性。 第一个依赖项（Assembly1）是硬绑定的适当候选项，第二个依赖项（Assembly2）不是。

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

程序集名称不包括文件扩展名。 可以使用显示名称。

指定程序集的默认绑定提示

只有程序集需要默认绑定提示，这些程序集将立即和频繁地供依赖于它们的任何应用程序使用。 将 DefaultDependencyAttribute with LoadHint.Always 应用于此类程序集以指定应使用硬绑定。

Microsoft用于 DefaultDependencyAttribute 指定硬绑定是 .NET Framework 中极少数程序集的默认值，例如 mscorlib.dll。

延迟处理

为非常大的应用程序生成本机映像可能需要相当长的时间。 同样，对共享组件所做的更改或更改计算机设置可能需要更新许多本机映像。 该 install 作和 update 作有一个选项 /queue ，可将作排入队列，以供本机映像服务延迟执行。 此外，Ngen.exe 还有queueexecuteQueuedItems一些作，用于对服务进行一些控制。 有关详细信息，请参阅 本机映像服务。

本机映像和 JIT 编译

如果 Ngen.exe 遇到无法生成的程序集中的任何方法，则会将其从本机映像中排除。 当运行时执行此程序集时，它将还原为本机映像中不包含的方法的 JIT 编译。

此外，如果程序集已升级，或者映像因任何原因失效，则不会使用本机映像。

无效图像

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

• .NET Framework 的版本。

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

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

• 安全因素。

Ngen.exe 生成本机映像时记录此信息。 执行程序集时，运行时将查找使用与计算机当前环境匹配的选项和设置生成的本机映像。 如果运行时找不到匹配的本机映像，则运行时将还原为程序集的 JIT 编译。 对计算机的设置和环境进行的以下更改会导致本机映像无效：

• .NET Framework 的版本。

  如果将更新应用到 .NET Framework，则使用 Ngen.exe 创建的所有本机映像都无效。 因此，.NET Framework 的所有更新都执行 Ngen Update 命令，以确保重新生成所有本机映像。 .NET Framework 会自动为其安装的 .NET Framework 库创建新的本机映像。

• 程序集的确切标识。

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

• 程序集引用的任何程序集的确切标识。

  如果更新托管程序集，则直接或间接依赖该程序集的所有本机映像都变得无效，需要重新生成。 这包括普通引用和硬绑定依赖项。 每当应用软件更新时，安装程序都应执行命令 Ngen Update ，以确保重新生成所有依赖的本机映像。

• 安全因素。

  更改计算机安全策略以限制以前授予程序集的权限可能会导致以前编译的本机映像使该程序集失效。

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

Troubleshooting

以下故障排除主题允许查看正在使用哪些本机映像，哪些本机映像不能由应用程序使用，以确定 JIT 编译器何时开始编译方法，并演示如何选择退出指定方法的本机映像编译。

程序集绑定日志查看器

若要确认应用程序正在使用本机映像，可以使用 Fuslogvw.exe（程序集绑定日志查看器）。 在绑定日志查看器窗口的“日志类别”框中选择“本机映像”。 Fuslogvw.exe 提供有关本机映像被拒绝的原因的信息。

JITCompilationStart 托管调试助手

可以使用 jitCompilationStart 托管调试助手（MDA）来确定 JIT 编译器何时开始编译函数。

选择退出本机映像生成

在某些情况下，NGen.exe 可能难以为特定方法生成本机映像，或者你希望将方法编译为 JIT，而不是编译为本机映像。 在这种情况下，可以使用 System.Runtime.BypassNGenAttribute 该属性来防止 NGen.exe 为特定方法生成本机映像。 该属性必须单独应用于不希望包含在本机映像中的代码的每个方法。 NGen.exe 识别属性，并且不会在相应方法的本机映像中生成代码。

但是，请注意，该 BypassNGenAttribute 类型未定义为 .NET Framework 类库中的类型。 若要在代码中使用属性，必须先按如下所示定义它：

namespace System.Runtime
{
   [AttributeUsage(AttributeTargets.Method |
                   AttributeTargets.Constructor |
                   AttributeTargets.Property)]
   public class BypassNGenAttribute : Attribute
   {
   }
}

Namespace System.Runtime
    <AttributeUsage(AttributeTargets.Method Or
                    AttributeTargets.Constructor Or
                    AttributeTargets.Property)>
    Public Class BypassNGenAttribute : Inherits Attribute
    End Class
End Namespace

然后，可以按方法应用属性。 以下示例指示本机映像生成器不应为 ExampleClass.ToJITCompile 该方法生成本机映像。

using System;
using System.Runtime;

public class ExampleClass
{
   [BypassNGen]
   public void ToJITCompile()
   {
   }
}

Imports System.Runtime

Public Class ExampleClass
    <BypassNGen>
    Public Sub ToJITCompile()
    End Sub
End Class

例子

以下命令为 ClientApp.exe位于当前目录中的本机映像生成本机映像，并在本机映像缓存中安装映像。 如果程序集存在配置文件，Ngen.exe 使用它。 此外，将为引用的任何 .dll 文件 ClientApp.exe 生成本机映像。

ngen install ClientApp.exe

安装有 Ngen.exe 的映像也称为根。 根可以是应用程序或共享组件。

以下命令生成具有指定路径的本机映像 MyAssembly.exe 。

ngen install c:\myfiles\MyAssembly.exe

查找程序集及其依赖项时，Ngen.exe 使用公共语言运行时使用的相同探测逻辑。 默认情况下，包含的 ClientApp.exe 目录用作应用程序基目录，并且所有程序集探测都从此目录中开始。 可以使用此选项替代此行为 /AppBase 。

程序集可以具有不带引用的依赖项，例如，如果程序集使用 Assembly.Load 该方法加载 .dll 文件。 可以使用应用程序程序集 /ExeConfig 的配置信息和选项为此类 .dll 文件创建本机映像。 以下命令生成本机映像，以便 MyLib.dll 从 MyApp.exe中使用该配置信息。

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

删除应用程序时，不会删除以这种方式安装的程序集。

若要卸载依赖项，请使用用于安装依赖项的相同命令行选项。 以下命令卸载 MyLib.dll 上一个示例中的命令。

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

若要在全局程序集缓存中为程序集创建本机映像，请使用程序集的显示名称。 例如：

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

NGen.exe 为安装的每个方案生成一组单独的映像。 例如，以下命令安装一组完整的本机映像用于正常作，另一个用于调试的完整集，第三个用于分析：

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

显示本机映像缓存

在缓存中安装本机映像后，可以使用 Ngen.exe显示它们。 以下命令显示本机映像缓存中的所有本机映像。

ngen display

该 display 作首先列出所有根程序集，后跟计算机上所有本机映像的列表。

使用程序集的简单名称仅显示该程序集的信息。 以下命令显示本机映像缓存中的所有本机映像，这些映像与部分名称 MyAssembly、依赖项以及依赖 MyAssembly的所有根匹配：

ngen display MyAssembly

了解哪些根依赖于共享组件程序集，有助于在升级共享组件后确定作的影响 update 。

如果指定程序集的文件扩展名，则必须从包含程序集的目录中指定路径或执行 Ngen.exe：

ngen display c:\myApps\MyAssembly.exe

以下命令使用名称和 MyAssembly 版本 1.0.0.0 显示本机映像缓存中的所有本机映像。

ngen display "myAssembly, version=1.0.0.0"

更新映像

映像通常在共享组件升级后更新。 若要更新已更改或其依赖项已更改的所有本机映像，请使用 update 不带参数的作。

ngen update

更新所有映像可能是一个漫长的过程。 可以使用此选项将更新排队供本机映像服务 /queue 执行。 有关选项和安装优先级的详细信息 /queue ，请参阅 本机映像服务。

ngen update /queue

卸载映像

Ngen.exe 维护依赖项列表，以便仅在删除依赖于它们的所有程序集时删除共享组件。 此外，如果已将其安装为根组件，则不会删除共享组件。

以下命令卸载根 ClientApp.exe的所有方案：

ngen uninstall ClientApp

该 uninstall 作可用于删除特定方案。 以下命令卸载以下各项的所有调试方案 ClientApp.exe：

ngen uninstall ClientApp /debug

以下命令卸载特定版本 ClientApp.exe的所有方案：

ngen uninstall "ClientApp, Version=1.0.0.0"

以下命令卸载该程序集的所有方案 "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"
ngen uninstall "ClientApp, Version=1.0.0.0, Culture=neutral,
  PublicKeyToken=3c7ba247adcd2081, processorArchitecture=MSIL" /debug

与作 install 一样，提供扩展需要从包含程序集的目录中执行 Ngen.exe 或指定完整路径。

有关本机映像服务的示例，请参阅 本机映像服务。

本机映像任务

本机映像任务是生成和维护本机映像的 Windows 任务。 本机映像任务为受支持的方案自动生成并回收本机映像。 它还使安装程序能够使用 Ngen.exe（本机映像生成器） 在延迟时间创建和更新本机映像。

为计算机上支持的每个 CPU 体系结构注册一次本机映像任务，以允许针对每个体系结构的应用程序进行编译：

在 Windows 8 或更高版本上运行时，本机映像任务在 .NET Framework 4.5 及更高版本中可用。 在早期版本的 Windows 上，.NET Framework 使用 本机映像服务。

任务生存期

通常，当计算机处于空闲状态时，Windows 任务计划程序每晚都会启动本机映像任务。 该任务检查应用程序安装程序排队的任何延迟工作、任何延迟的本机映像更新请求以及任何自动创建映像。 该任务完成未完成的工作项，然后关闭。 如果计算机在任务运行时停止处于空闲状态，则任务将停止。

还可以通过任务计划程序 UI 或手动调用 NGen.exe来手动启动本机映像任务。 如果任务是通过上述任一方法启动的，则在计算机不再空闲时将继续运行。 使用 NGen.exe 手动创建的映像的优先级是启用应用程序安装程序的可预测行为。

本机映像服务

本机映像服务是生成和维护本机映像的 Windows 服务。 本机映像服务允许开发人员将本机映像的安装和更新推迟到计算机空闲时的时间段。

通常，本机映像服务由安装程序（安装程序）为应用程序或更新启动。 对于优先级 3作，服务会在计算机上的空闲时间执行。 该服务会保存其状态，并在必要时继续执行多次重启。 多个映像编译可以排队。

该服务还与手动 Ngen.exe 命令交互。 手动命令优先于后台活动。

启动延迟作

在开始安装或升级之前，建议暂停服务。 这可确保服务不会在安装程序复制文件或将程序集放入全局程序集缓存时执行。 以下 Ngen.exe 命令行暂停服务：

ngen queue pause

当所有延迟的作都已排队时，以下命令允许服务恢复：

ngen queue continue

若要在安装新应用程序或更新共享组件时延迟本机映像生成，请将 /queue 此选项用于 install 或 update 作。 以下 Ngen.exe 命令行为共享组件安装本机映像，并执行可能受影响的所有根的更新：

ngen install MyComponent /queue
ngen update /queue

该 update 作会重新生成所有已失效的本机映像，而不仅仅是那些使用该 MyComponent映像的映像。

如果应用程序包含许多根，则可以控制延迟作的优先级。 以下命令将三个根的安装排在队列中。 Assembly1 首先安装，无需等待空闲时间。 Assembly2 还会安装，无需等待空闲时间，但在所有优先级 1作完成后。 Assembly3 当服务检测到计算机处于空闲状态时，将安装 。

ngen install Assembly1 /queue:1
ngen install Assembly2 /queue:2
ngen install Assembly3 /queue:3

可以使用该 executeQueuedItems 作强制排队作同步发生。 如果提供可选优先级，则此作仅影响优先级等于或较低优先级的排队作。 默认优先级为 3，因此以下 Ngen.exe 命令会立即处理所有排队作，在完成之前不会返回：

ngen executeQueuedItems

同步命令由 Ngen.exe 执行，不使用本机映像服务。 可以在本机映像服务运行时使用 Ngen.exe 执行作。

服务关闭

执行包含 /queue 该选项的 Ngen.exe 命令后，服务将在后台运行，直到完成所有作。 该服务保存其状态，以便在必要时继续执行多次重新启动。 当服务检测到没有更多排队的作时，它会重置其状态，以便在下次启动计算机时不会重启，然后关闭自身。

服务与客户端交互

在 .NET Framework 版本 2.0 中，与本机映像服务的唯一交互是通过命令行工具 Ngen.exe。 使用安装脚本中的命令行工具将本机映像服务的作排入队列，并与服务交互。

另请参阅

• 工具
• 托管执行过程
• 运行时如何定位程序集
• 开发人员命令行 shell