Export (0) Print
Expand All

Advanced Native Image Generation Scenarios

.NET Framework 4.5

This topic contains information that may be useful to developers and administrators who create native images manually.

The Native Image Generator (Ngen.exe) generates native images for the specified assembly and all its dependencies. Dependencies are determined from references in the assembly manifest. The only scenario in which you have to install a dependency separately is when the application loads it by using reflection (for example, by calling the Assembly.Load method), and the dependency is not eligible for automatic native image generation. See Creating Native Images.

Important note Important

Do not use the Assembly.LoadFrom method with native images. An image that is loaded with this method cannot be used by other assemblies in the execution context.

Ngen.exe maintains a count on dependencies. For example, suppose that MyAssembly.exe and YourAssembly.exe are both installed in the native image cache, and both have references to OurDependency.dll. Uninstalling MyAssembly.exe does not uninstall OurDependency.dll. The DLL is removed only when YourAssembly.exe is also uninstalled.

If you are generating a native image for an assembly in the global assembly cache, specify its display name. See Assembly.FullName.

A native image is called a root if it was directly created by an Ngen.exe command. If a native image was created as a result of an Ngen.exe command that targeted a different assembly, it is not a root.

The native images that Ngen.exe generates can be shared across application domains. This means that you can use Ngen.exe in application scenarios that require assemblies to be shared across application domains. To specify domain neutrality:

  1. Apply the LoaderOptimizationAttribute attribute to your application.

  2. Set the AppDomainSetup.LoaderOptimization property when you create setup information for a new application domain.

Always use domain-neutral code when loading the same assembly into multiple application domains. If a native image is loaded into a nonshared application domain after having been loaded into a shared domain, it cannot be used.

Note Note

Domain-neutral code cannot be unloaded, and performance may be slightly slower, particularly when accessing static members.

After you have generated a native image for an assembly, the runtime automatically attempts to locate and use this native image each time it runs the assembly. Multiple images can be generated, depending on usage scenarios.

For example, if you run an assembly in a debugging or profiling scenario, the runtime looks for a native image that was generated with the Ngen.exe /Debug or /Profile option. If it is unable to find a matching native image, the runtime reverts to standard JIT compilation. The only way to debug native images is to create a native image with the /Debug option.

The Ngen Uninstall command also recognize scenarios, so you can uninstall all scenarios or only selected scenarios.

Hard binding increases throughput and reduces working set size for native images. The disadvantage of hard binding is that all the images that are hard-bound to an assembly must be loaded when the assembly is loaded. This can significantly increase startup time for a large application.

Hard binding is appropriate for dependencies that are loaded in all performance-critical scenarios for your application. As with any aspect of native image use, careful performance measurements are the only way to determine whether hard binding improves your application's performance.

The DependencyAttribute and DefaultDependencyAttribute attributes enable you to provide hard binding hints to Ngen.exe.

Note Note

These attributes are hints to Ngen.exe, not commands. Using them does not guarantee hard binding. The meaning of these attributes may change in future releases.

Apply the DependencyAttribute to an assembly to indicate the likelihood that a specified dependency will be loaded. LoadHint.Always indicates that hard binding is appropriate, LoadHint.Default indicates that the default for the dependency should be used, and LoadHint.Sometimes indicates that hard binding is not appropriate.

The following code shows the attributes for an assembly that has two dependencies. The first dependency (Assembly1) is an appropriate candidate for hard binding, but the second dependency (Assembly2) is not.

using System.Runtime.CompilerServices;
[assembly:DependencyAttribute("Assembly1", LoadHint.Always)]
[assembly:DependencyAttribute("Assembly2", LoadHint.Sometimes)]

The assembly name does not include the file name extension. Display names can be used.

Specify default binding hints only for assemblies that will be used immediately and frequently by any application that has a dependency on them. Apply the DefaultDependencyAttribute with LoadHint.Always to such assemblies to specify that hard binding should be used.

Note Note

There is no reason to apply DefaultDependencyAttribute to .dll assemblies that do not fall into this category, because applying the attribute with any value other than LoadHint.Always has the same effect as not applying the attribute at all.

Microsoft uses the DefaultDependencyAttribute to specify that hard binding is the default for a very small number of assemblies in the .NET Framework, such as mscorlib.dll.

When you use Ngen.exe to create a native image of an assembly, the output depends on the command-line options that you specify and certain settings on your computer. These settings include the following:

  • The version of the .NET Framework.

  • The version of the operating system, if the change is from the Windows 9x family to the Windows NT family.

  • The exact identity of the assembly (recompilation changes the identity).

  • The exact identity of all assemblies that the assembly references (recompilation changes the identity).

  • Security factors.

Ngen.exe records this information when it generates a native image. When you execute an assembly, the runtime looks for the native image generated with options and settings that match the computer's current environment. The runtime reverts to JIT compilation of an assembly if it cannot find a matching native image. The following changes to a computer's settings and environment cause native images to become invalid:

  • The version of the .NET Framework.

    If you apply an update to the .NET Framework, all native images that you have created using Ngen.exe become invalid. For this reason, all updates of the .NET Framework execute the Ngen Update command, to ensure that all native images are regenerated. The .NET Framework automatically creates new native images for the .NET Framework libraries that it installs.

  • The version of the operating system, if the change is from the Windows 9x family to the Windows NT family.

    For example, if the version of the operating system running on a computer changes from Windows 98 to Windows XP, all native images stored in the native image cache become invalid. However, if the operating system changes from Windows 2000 to Windows XP, the images are not invalidated.

  • The exact identity of the assembly.

    If you recompile an assembly, the assembly's corresponding native image becomes invalid.

  • The exact identity of any assemblies the assembly references.

    If you update a managed assembly, all native images that directly or indirectly depend on that assembly become invalid and need to be regenerated. This includes both ordinary references and hard-bound dependencies. Whenever a software update is applied, the installation program should execute an Ngen Update command to ensure that all dependent native images are regenerated.

  • Security factors.

    Changing machine security policy to restrict permissions previously granted to an assembly can cause a previously compiled native image for that assembly to become invalid.

    For detailed information about how the common language runtime administers code access security and how to use permissions, see Code Access Security.

To confirm that native images are being used by your application, you can use the Fuslogvw.exe (Assembly Binding Log Viewer). Select Native Images in the Log Categories box on the binding log viewer window. Fuslogvw.exe provides information about why a native image was rejected.

If Ngen.exe encounters any methods in an assembly that it cannot generate, it excludes them from the native image. When the runtime executes this assembly, it reverts to JIT compilation for the methods that were not included in the native image. You can use the jitCompilationStart managed debugging assistant (MDA) to determine when the JIT compiler starts to compile a function.

© 2014 Microsoft