Native Image Generator (Ngen.exe)
The Native Image Generator creates a native image from a managed assembly and installs it into the native image cache on the local computer. The native image cache is a reserved area of the global assembly cache. Once you create a native image for an assembly, the runtime automatically uses that native image each time it runs the assembly. You do not have to perform any additional procedures to cause the runtime to use a native image. Running Ngen.exe on an assembly allows the assembly to load and execute faster, because it restores code and data structures from the native image cache rather than generating them dynamically.
ngen [options] [assemblyName |assemblyPath ]
| Argument | Description |
|---|---|
| assemblyName | The name of the assembly for which to generate a native image. The assembly must be located in the current directory. You can supply either a partially specified assembly name such as myAssembly or a fully specified assembly name such as myAssembly, Version=2.0.0.0, Culture=neutral, PublicKeyToken=0038abc9deabfle5. You must use a fully specified assembly name if you want Ngen.exe to locate and use an assembly's publisher policy file. |
| assemblyPath | The explicit path of the assembly for which to generate a native image. You can specify a full path to an assembly such as c:\applications\myApp\myApp.exe, a relative path such as ..\applications\myApp\myApp.exe, or a file name such as myApp.exe.
If you specify a file name such as To allow Ngen.exe to identify an assembly as an executable and locate its configuration file, you should use the assemblyPath argument to specify assemblies with an .exe extension. If you specify more than one assembly on the command line, only one of the assemblies can be an executable file. The tool applies the executable file's binding properties (application base and any configuration files) to the other assemblies that you specify. |
| Option | Description |
|---|---|
| /debug | Generates a native image to be used by a debugger in normal debugging mode. |
| /debugopt | Generates a native image to be used by a debugger in the common language runtime's optimized debugging mode. See your debugger's documentation for details about how to activate this mode. |
| /delete [assemblyName | assemblyPath |
*] |
Deletes the native images in the native image cache for the specified assemblyName or assemblyPath. If you specify the '*' parameter, the tool deletes all native images in the native image cache. If you do not specify a parameter with the /delete option, the tool displays an error message.
When you uninstall a version of the .NET Framework, the uninstall process uses the /delete option to remove all native images for the version of the .NET Framework being uninstalled. This includes native images created for .NET Framework assemblies at install time as well as any native images created by the user for custom assemblies. If you specify the /delete * option with the /show option, the tool displays a list of the native images it deletes. When multiple versions of the .NET Framework are installed on the same computer at the same time, to delete a native image you must use the same version of Ngen.exe that was used to create the native image. Note This option only affects the native images generated with Ngen.exe. It has no effect on the actual assemblies. |
| /help | Displays command syntax and options for the tool. |
| /nologo | Suppresses the Microsoft startup banner display. |
| /prof | Generates a native image to be used by a profiler that uses instrumented code. See your profiler's documentation to determine whether your profiler requires instrumented code. |
| /show | Displays the existing files in the native image cache for the specified assemblyName or assemblyPath. If you do not specify an argument, the tool displays the entire contents of the native image cache. This option displays assembly definition information for the source assembly and any special code configuration options for each native image.
If you specify this option with the /delete * option, the tool displays a list of the native images it deletes. |
| /showversion | Displays the version of the runtime that Ngen.exe will use to generate a native image for the specified assembly. When multiple versions of the .NET Framework are installed on the same computer at the same time, use this option to determine the version that the tool will use. For more information about running multiple versions of the runtime, see Side-By-Side Execution.
Note This option does not generate a native image. |
| /silent | Suppresses the display of success messages. |
| /? | Displays command syntax and options for the tool. |
Remarks
Ngen.exe does not use standard assembly probing rules to locate the assemblies you specify on the command line. Ngen.exe looks only in the current directory for assemblies that you specify. Therefore, to allow Ngen.exe to locate your assemblies, you should either set your working directory to the directory that contains the assemblies you want to create native images for or specify exact paths to the assemblies.
A native image is a file containing compiled processor-specific machine code. Note that the native image that Ngen.exe generates cannot be shared across Application Domains. Therefore, you cannot use Ngen.exe in application scenarios, such as ASP.NET, that require assemblies to be shared across application domains.
Pre-compiling assemblies with Ngen.exe can improve the startup time for applications, because much of the work required to execute code has been done in advance. Therefore, it is more appropriate to use Ngen.exe for client-side applications where you have determined that the CPU cycles consumed by JIT compilation cause slower performance.
Because there are many factors that affect the startup time of an application, you should carefully determine which applications would benefit from the use of Ngen.exe. Experiment by running both a JIT-compiled and a pre-compiled version of a candidate assembly in the environment in which it will be used. This will allow you to compare the startup times for the same assembly executing under different compilation schemes.
Note To run Ngen.exe, you must have administrative privileges.
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. 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 /debug, /debugopt, or /prof options. If it is unable to find a matching native image, the runtime reverts to standard JIT Compilation.
If you run Ngen.exe on an assembly that has a debuggable code attribute, depending on the attribute's flags, the tool automatically generates code as if you had specified the /debug or /debugopt options.
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 will revert to JIT compilation for the methods that were not included in the native image.
When you use Ngen.exe to create a native image of an assembly, the output depends upon 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 CPU type.
- The version of the operating system.
- The exact identity of the assembly (recompilation changes identity).
- The exact identity of all assemblies that the assembly references (recompilation changes 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 a patch, QFE, or update to the .NET Framework, all native images that you have created manually using Ngen.exe become invalid. These assemblies will still run, but the runtime will not load the assembly's corresponding native image. You must manually create new native images for these assemblies.
The .NET Framework automatically creates new native images for the .NET Framework libraries that it installs.
The CPU type.
If you upgrade a computer's processor to a new processor family, all native images stored in the native image cache become invalid.
The version of the operating system.
If the version of the operating system running on a computer changes, all native images stored in the native image cache become invalid.
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 recompile any of the assemblies that an assembly references, the assembly's corresponding native image becomes invalid.
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. Specifically, revoking any of the following permissions causes an assembly's current native image to become invalid:
- A declarative inheritance permission demanded by a class the assembly derives from.
- A declarative link-time permission demanded by a method that the assembly calls.
- SkipVerification permission, if the assembly contains any unverifiable methods. For more information about this permission, see the SecurityPermissionAttribute.SkipVerification Property.
- UnmanagedCode permission, if the assembly makes any PInvoke calls. For more information about this permission, see the SecurityPermissionAttribute.UnmanagedCode Property.
If you run Ngen.exe on an assembly with code access security turned off, the native image it generates will become invalid when code access security is turned on. Note that by default code access security is on.
For detailed information about how the common language runtime administers code access security and how to use permissions, see Code Access Security
Note In version 1.0 of the common language runtime, there is no automatic creation or deletion of native images that become invalid. You must manually create and delete all native images using Ngen.exe.
If you use Ngen.exe to generate native images for an application at install time, you must specify the application file name and the fully specified assembly names of the .dll files the application referenced at the time it was compiled. Supplying the fully specified assembly names of the DLLs that an application references, enables Ngen.exe to access the publisher policy files for the referenced assemblies. In the future, if the DLLs are updated and publisher policy is used for version redirection, Ngen.exe will apply the publisher policy.
You can obtain the fully specified assembly names to use by running Ildasm.exe on an application and viewing its assembly manifest. The manifest displays the assembly name, version, culture, and public key token for the DLLs the application referenced at the time it was compiled. For example, if you want to create a native image for an application called ClientApp.exe that was compiled with myLibrary.dll, version 1.0.0.0, culture=neutral, and PublicKeyToken=0038abc9deabfle5, use the command ngen ClientApp.exe "myLibrary, Version=1.0.0.0, Culture=neutral, PublicKeyToken=0038abc9deabfle5".
Note that the previous example will not generate native images for the assemblies that myLibrary.dll references. To determine the fully specified names of the assemblies that myLibrary.dll references, run Ildasm.exe on myLibrary.dll. For example, if you run Ildasm.exe on myLibrary.dll and determine that it references myMath.dll, version 1.0.0.0, culture=neutral, and PublicKeyToken=0039def8abcbste7, use the following command to generate native images for ClientApp.exe's entire tree of assembly references.
ngen ClientApp.exe "myLibrary, Version=1.0.0.0, Culture=neutral, PublicKeyToken=0038abc9deabfle5", "myMath, Version=1.0.0.0, Culture=neutral, PublicKeyToken=0039def8abcbste7".
For more information about this format, see the Examples section later in this topic.
The uninstall process for an application should use the /delete [assemblyName | assemblyPath] option to remove the native images that were created at the time the application was installed. You must specify the specific native image to delete using the assemblyName or assemblyPath parameter. Specifying /delete * removes all native images in the native image cache; specifying the /delete option without parameters produces an error.
Examples
The following command generates a native image for ClientApp.exe, located in the current directory. If a configuration file exists for the application, Ngen.exe will use it. The tool will not generate native images for any DLLs that ClientApp.exe references.
ngen ClientApp.exe
If ClientApp.exe directly references two DLLs, myLibOne.dll and myLibTwo.dll, you must supply Ngen.exe with the fully specified assembly names for these DLLs to generate native images for them. Run Ildasm.exe over ClientApp.exe to determine the fully specified assembly names of the referenced DLLs. For the purpose of this example, the fully specified assembly names of myLibOne.dll and myLibTwo.dll are "myLibOne, Version=1.0.0.0, Culture=neutral, PublicKeyToken=0038abc9deabfle5" and "myLibTwo, Version=1.0.0.0, Culture=neutral, PublicKeyToken=0038abc9deabfle5". Using this information, the following command generates native images for ClientApp.exe, myLibOne.dll, and myLibTwo.dll. If a configuration file exists for ClientApp.exe, Ngen.exe will use it. If a publisher policy file exists for myLibOne.dll or myLibTwo.dll, Ngen.exe will use it.
ngen ClientApp.exe "myLibOne, Version=1.0.0.0, Culture=neutral, PublicKeyToken=0038abc9deabfle5", "myLibTwo, Version=1.0.0.0, Culture=neutral, PublicKeyToken=0038abc9deabfle5"
In the previous example, the DLLs myLibOne.dll and myLibTwo.dll could reference other assemblies. To determine the fully specified assembly names of the referenced assemblies, run Ildasm.exe on myLibOne.dll and myLibTwo.dll. For the purpose of this example, suppose that myLibOne.dll does not reference any other assemblies, and myLibTwo.dll references "myMath, Version=1.0.0.0, Culture=neutral, PublicKeyToken=0039def8abcbste7". Using this information, the following command generates native images for the application's entire tree of assembly references.
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"
The following command generates a native image for myAssembly.exe with the specified path.
ngen c:\myfiles\myAssembly.exe
The following command generates a native image for myLibrary.dll, with the specified path.
ngen c:\myfiles\myLibrary.dll
Ngen.exe looks in the native image cache to delete an assembly specified with a partial assembly name. The following command deletes all native images with the name myAssembly.
ngen /delete myAssembly
The following command deletes the native image myAssembly with the fully specified assembly name.
ngen /delete "myAssembly, Version=1.0.0.0, Culture=neutral, PublicKeyToken=0038abc9deabfle5"
The following command displays all native images in the native image cache.
ngen /show
The following command displays all native images in the native image cache with the name myAssembly.
ngen /show myAssembly
The following command displays all native images in the native image cache with the name myAssembly and the version 1.0.
ngen /show "myAssembly, version=1.0.0.0"
See Also
.NET Framework Tools | Compiling MSIL to Native Code | How the Runtime Locates Assemblies