This machine image generator creates a native image of the host set and installs the image to the local image cache of the local computer. This machine image cache is a reserved area for global program cache. Once you create a native image for a set, the run library automatically uses the native image when you run the assembly. You don't have to perform any other procedure, you can use the native image to make the run library. Running NGEN.exe on the assembly to increase the loading and execution speed of the assembly, because it can restore code and data structures from the native image cache, rather than dynamically generating them.
NGen [options] [askMBLYNAME | AssemblyPath]
Parameter Description AssemblyName is the name of the assembly of this machine image. The assembly must be in the current directory. You can provide some specified program names (such as myassembly) or fully specified program names (such as Myassembly, Version = 2.0.0.0, Culture = NEUTRAL, PUBLICKEYTOKEN = 0038Abc9deabfle5). If you want nGen.exe to find and use the publisher policy file of the assembly, you must use a fully specified program set name. AssemblyPath is an explicit path to the assembly of this machine image. You can specify the full path of the assembly (such as C: /Applications/myApp/myapp.exe), relative path (such as ../applications/myapp/myapp.exe) or file name (such as MyApp.exe). If the file name (such as myapp.exe) is specified without specifying a complete or relative path, the assembly must be in the current directory. To make NGen.exe to identify the assembly as an executable file and find its configuration file, you should use the assemblyPath parameter to specify the assembly with the .exe extension. If you specify more than one assembly on the command line, only one of them is an executable file. This tool applies the binding property of the executable to the other assembly you specified by the binding property (application base, and any configuration file).
Option Description / Debug generates the native image that will be used by the debugger in normal debug mode. / debugopt generates native images used by the debugger in the optimized debug mode of the public language runtime. For more information on how to activate this mode, see your debugger documentation. / delete [assemblyname | assemblyPath | *] deletes the native image of the AssemblyName or AssemblyPath specified in the native image cache. If the "*" parameter is specified, the tool will delete all the native images in the native image cache. If you use the / delete option without specifying a parameter, the tool will display an error message. When uninstalling a .NET Framework version, uninstalling the process uses the / delete option to delete all of the local images of the uninstalled .NET Framework version. This includes native images created when installed .NET Framework assemblies, as well as any native image created by the user to customize the set. If you specify the / show option and / delete * option, the tool displays a list of local images it deleted. When multiple .NET Framework versions are installed on the same computer, you must use the same NGen.exe version used when you create a native image, you can delete the native image.
Note This option only affects the native image generated by nGen.exe, which does not affect the actual assembly.
/ Help shows the command syntax and options for the tool. / NOLOGO Cancels the Microsoft Startup title. / PROF generates a native image that will be used by an analyzer using a specified code. See your analyzer documentation to determine if your analyzer requires a specification code. / show displays an existing file in the native image cache for the specified AssemblyName or AssemblyPath. If you do not specify a parameter, the tool will display all the contents of the native image cache. This option displays the assembly definition information of the source assembly and any special code configuration option for each of the machine images. If this option is specified with the / delete * option, the tool displays a list of local images it deleted. / showVersion Displays the Runtuity Version used by NGEN.EXE to generate the native image of the specified assembly. When multiple .NET Framework versions are installed on the same computer, use this option to determine the version of the tool will use. For more information on running multiple runs versions, see the Side-By-Side execution. Note This option does not have a cost of the machine image.
/ Silent cancels the success message. /? Display the command syntax and options for the tool.
Note
NGen.exe does not use the standard assembly probe rules to locate the assembly you specified on the command line. NGen.exe only finds the assembly you specified in the current directory. Therefore, to make NGEN.exe can find an assembly, set the work directory to the directory where the assembly of this machine image is to specify the exact path of the assembly.
The native image is a file containing a specific machine code that has been compiled. Note that native images generated by NGen.exe cannot be shared between applications. Therefore, NGEN.exe cannot be used in an application solution (such as ASP.NET) requiring a shared assembly between the application domain.
By the NGEN.EXE precompiled assembly can reduce the startup time of the application, because the large number of work required to execute code is completed in advance. Therefore, if you have determined that the performance reduction is the CPU cycle consumed in the client application in the client application, it is best to use NGen.exe for client applications.
Because there are many factors that affect the startup time of the application, it should be carefully determined which applications will benefit from using NGen.exe. To this end, the following tests should be carried out: JIT compilation versions and precompiled versions of the assembly will be run in the environment where the candidate set is used. This will enable you to compare the startup time of the same assembly under different compilation schemes.
Note To run NGEN.exe, you must have administrator privileges.
After you generate a native image of an assembly, whenever the running is running the assembly, you will automatically try and use the native image. For example, if you run an assembly in a debug or analysis scheme, the run library will look up the native image generated by the / debug, / debugopt, or / pROF option. If the run library cannot find a matching native image, it will recover to standard JIT compilation.
If you run NGEN.exe on the program with the debug code properties, the tool automatically generates code based on the flag of this property, just like the / debug or / debugopt option has been specified.
If NGEN.exe encounters any way it cannot generate in the program set, it will be excluded from the native image. When the running library executes this assembly, for those that are not included in the native image, it will turn to JIT compilation.
When you use nGen.exe to create a native image of the assembly, the output depends on the command line options you specify and some settings on your computer. These settings include:
The version of the .NET Framework. CPU type. The version of the operating system. The exact logo of the assembly (recompiling will change the logo). The exact logo of all the assemblies referenced by the assembly (re-compiling will change the logo). safety factors.
NGEN.EXE logs this information when generating this machine image. When you execute an assembly, the Runture library will find options and setting the generated native image with the current environment that matches the computer. If the run library does not find a matching native image, it will restore JIT compilation to the assembly. The following changes to your computer will cause the native image to fail: The version of .NET Framework. If you apply a patch, QFE, or update to .NET Framework, all native images created by nGen.exe will be invalid. These assemblies are still running, but the run library does not load the corresponding native image of the assembly. You must manually create a new native image for these assemblies. .NET Framework automatically creates a new native image for its installed .NET Framework library. CPU type. If you upgrade your computer's processor to your new processor series, all native images stored in the native image cache will be invalid. The version of the operating system. If the version of the operating system running on your computer changes, all native images stored in the native image cache will be invalid. The exact logo of the assembly. If the assembly is recompiled, the corresponding native image of the assembly will be invalid. The exact logo of any assembly referenced by the assembly. If any of the assembly references is recompiled, the corresponding native image of the assembly will be invalid. safety factors. Change the computer security policy to limit the permissions previously granted to an assembly, which will cause the previously compiled native image of the assembly to fail. Specifically, any permissions to undo will result in the current native image of the assembly:
Declarative inheritance required by the class of derived assembly. Declarative linkage required by the method of the assembly call. SkiPVerification Permissions (if the program set contains any way to verify). For more information on this permissions, see the SecurityPerMissionAttribute.skiPVerification property. UnmanageDcode privilege (if the assembly is made for any Pinvoke call). For more information on this permission, see the SecurityPermissionAttribute.unManageDcode property. If you run NGEN.exe on the program set that closes the code access secure, the native image it generate will fail when the open code is accessed. Note that by default, code access security is open. For more information on how to manage code access security and how to use permissions, see Code Access Security.
Note that in the Public Language Runture library version 1.0, the failure of the native image is not automatically created or deleted. You must manually create or delete all native images with nGen.exe.
If you use nGen.exe to generate a native image of an application when installing, you must specify the file name of the application, and the fully specified assembly name of the application that the application is referenced at compile. Provides a fully specified assembly name of the DLL file referenced by the application, allowing NGEN.exe to access the publisher policy files of the referenced assembly. In the future, if you update the DLL file and use the issuer policy to replace the version, NGen.exe will apply the issuer policy.
You can get the fully specified assembly name you want to use by running Ildasm.exe on your application and views your assembly list. This list shows the program set name, version, regional, and public key tag of the DLL file referenced by the application at compile. For example, if you want to create a native image for an application named ClientApp.exe, the application is used in version 1.0.0.0, regionality as a non-specific language, the public key is marked as a MYLIBRARY.DLL file compiled by 0038ABC9DEABFLE5. If you use the command nGen clientapp.exe "MYLIBRARY, VERSION = 1.0.0, Culture = 0038ABC9DEABFLE5". Note that the previous example does not generate a native image of the assembly referenced by MyLibrary.dll. To determine the fully specified name of the assembly referenced by myLibrary.dll, run Ildasm.exe on MyLibrary.dll. For example, if you run Ildasm.exe on MyLibrary.dll, and make sure it is a reference version of 1.0.0.0, the region is non-specific language, the public key is marked as 0039DEF8ABCBSTE7 mymath.dll, please use the following command to ClientApp.exe The entire assembly reference directory tree cost machine image.
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 on this format, see the "Example" section later in this topic.
The application's uninstall process should use the / delete [assemblyName | assemblyPath] option to remove the native image created when installing the application. You must specify a particular native image you want to delete using the assemblyname or askEMBLYPATH parameter. Specify / delete * will remove all of the native images in the native image cache; specify / delete option without specifying the parameters will generate an error.
Example
The following command generates this machine image for clientapp.exe in the current directory. If the application exists, NGen.exe will use it. This tool does not generate this machine image for any DLL references referenced by ClientApp.exe.
NGEN ClientApp.exe
If ClientApp.exe references two DLL (MyLibone.dll and MyLibTwo.dll), you must provide the full specified assembly name of these DLLs to NGEN.exe to generate this machine image. Run Ildasm.exe for ClientApp.exe to determine the fully specified assembly name of the referenced DLL. In this example, the fully specified assembly name of MYLIBONE.DLL and MYLIBTWO.DLL is "MYLIBONE, VERSION = 1.0.0.0, Culture = NEUTRAL, PUBLICKETOKEN = 0038abc9deabfle5" and "MYLIBTWO, Version = 1.0.0.0, Culture = Neutral, PublickeyToken = 0038ABC9DEABFLE5 ". With this information, the following command generates the native image of ClientApp.exe, MyLibone.dll, and MyLibTwo.dll. If ClientApp.exe exists, NGen.exe will use it. If MYLIBONE.DLL or MYLIBTWO.DLL exists, 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 above example, the DLL file MYLIBONE.DLL and MYLIBTWO.DLL can reference other assemblies. To determine the fully specified assembly name of the referenced assembly, run Ildasm.exe on MyLibone.dll and MyLibTwo.dll. In this example, assuming that MYLIBONE.DLL does not quote any other assembly, MyLibTwo.dll references "MyMath, Version = 1.0.0, Culture = neutral, publickeyToken = 0039DEF8ABCBSTE7". With this information, the following command references the entire assembly of the application to the directory tree cost machine image.
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 of myassembly.exe with a specified path.
NGEN C: /myfiles/myassembly.exe
The following command generates the native image of MyLibrary.dll according to the specified path.
NGEN C: /MYFILES /MYLIBRARY.DLL
NGEN.EXE looks up in the native image cache, deletes the assembly specified by the partial program name. The following command deletes all native images with myassembly names.
NGEN / DELETE MyassemblyMbly
The following command deletes the native image MYASSEMBLY with a fully specified assembly name. NGEN / DELETE "Myassembly, Version = 1.0.0.0, Culture = neutral, publickeytoken = 0038abc9deabfle5"
The following command displays all of the native images in the native image cache.
NGEN / Show
The following command displays all the native images named myassembly in the native image cache.
NGEN / SHOW MyassemblyMbly
The following command displays all the native images named myassembly, version of 1.0.
NGEN / Show "Myassembly, Version = 1.0.0.0"
