. NET Framework tool-local image generator (ngen.exe)

Native image builder creation hostingProgramSet, and install the image to the local computer's local image cache. The local image cache is the reserved region of the Global Assembly Cache. Once you create a local image for an assembly, the runtime automatically uses the local image every time you run the assembly. You can use a local image for the runtime without executing any other process. Running ngen.exe on an assembly can speed up assembly loading and execution because it can be restored from the local image cache.CodeInstead of generating them dynamically.

 
Ngen[Options] [Assemblyname|Assemblypath]
 

Parameters
Description

Assemblyname
The name of the Assembly for generating the cost machine image. The Assembly must be in the current directory. Some specified Assembly names (for exampleMyassembly) Or a fully-specified Assembly name (for exampleMyassembly, version = 2.0.0.0, culture = neutral, publickeytoken = 0038abc9deabfle5). If you want ngen.exe to locate and use the publisher policy file of the assembly, you must use the fully-specified Assembly name.

Assemblypath
The explicit path of the Assembly for generating the cost machine image. You can specify the full path of the Assembly (for exampleC: \ applications \ MyApp \ myapp.exe), Relative path (such ..\Applications \ MyApp \ myapp.exe) Or file name (suchMyapp.exe).

If you specify a file name (for exampleMyapp.exeWithout specifying a full or relative path, the Assembly must be in the current directory.

To enable ngen.exe to recognize an assembly as an executable file and find its configuration file, useAssemblypathThe parameter specifies 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 attributes of executable files (Application basics and any configuration files) to other specified assemblies.

Option
Description

/Debug
Generate a local image that will be used by the debugger in normal debugging mode.

/Debugopt
Generate a local image that will be used by the debugger in the optimized debugging mode of the Common Language Runtime Library. For more information about how to activate this mode, see your debugger documentation.

/Delete[Assemblyname|Assemblypath |

*]

DeletesAssemblynameOrAssemblypath. If the "*" parameter is specified, the tool deletes all local images in the local image cache. If you use/DeleteIf no parameter is specified, the tool displays the error message.

When a. NET Framework version is uninstalled, the uninstall process uses/DeleteOption to delete all local images of the unmounted. NET Framework version. This includes the local image created for the. NET Framework Assembly during installation and any local image created for the custom assembly. If both/ShowOptions and/Delete *The tool displays the list of local images it deletes.

When multiple. NET Framework versions are installed on the same computer at the same time, you must use the same ngen.exe version used to create a local image to delete the local image.

Note:This option only affects ngen.exe-generated local images, but does not affect the actual assembly.

/Help
Displays the command syntax and options of the tool.

/Nologo
Undisplay Microsoft startup title.

/Prof
Generate a local image that will be used by the analyzer that uses the standard code. See your analyzer documentation to determine whether your analyzer requires standard code.

/Show
For the specifiedAssemblynameOrAssemblypathDisplays existing files in the local image cache. If no parameter is specified, the tool displays all content in the local image cache. This option displays the Assembly definition information of the source set and any special code configuration options for each local image.

If/Delete *If this option is specified together, the tool displays the list of local images it deletes.

/Showversion
Displays the version of the Runtime library used by ngen.exe to generate the local image of the specified assembly. When multiple. NET Framework versions are installed on the same computer at the same time, you can use this option to determine the version that the tool will use. For more information about running multiple database versions, see parallel execution.

Note:This option does not generate a local image.

/Silent
The message indicating successful cancellation is displayed.

/?
Displays the command syntax and options of the tool.

Remarks

Ngen.exe does not use standard assembly detection rules to locate the Assembly you specified on the command line. Ngen.exe only searches for the specified assembly in the current directory. Therefore, to enable ngen.exe to locate the Assembly, set the working directory to the directory where the Assembly for which the local image is to be created, or specify the exact path of the Assembly.

A local image is a file that contains compiled processor-specific machine code. Ngen.exe-generated local images cannot be shared between application domains. Therefore, ngen.exe cannot be used in an application scheme (such as ASP. NET) that requires an assembly to be shared between application domains.

Ngen.exe pre-compiled assembly can reduce the startup time of the application, because much of the work required to execute the code has been done in advance. Therefore, if you have determined that the cause of performance degradation is the CPU cycle consumed by JIT compilation in the client application, you 'd better use ngen.exe for the client application.

Because many factors affect the startup time of the application, you should carefully determine which applications will benefit from using ngen.exe. To this end, the following experiment should be performed: the JIT and pre-compiled versions of the Assembly will be run in the environment where the candidate assembly will be used. This allows you to compare the startup time of the same assembly in different compilation schemes.

Note:To run ngen.exe, you must have administrator privileges.

After you generate a local image for an assembly, the local image is automatically located and used whenever the Runtime Library runs the assembly. For example, if you run an assembly in a debugging or analysis scheme/Debug,/DebugoptOr/ProfSpecifies the local image generated by option. If the runtime cannot find a matching local image, it will be restored to standard JIT compilation.

If you run ngen.exe on an assembly with the debuggable code property, the tool automatically generates code based on the flag of the property, as if you have already specified/DebugOr/DebugoptThe options are the same.

If ngen.exe encounters any methods that it cannot generate in the Assembly, it will exclude these methods from the local image. When the Runtime Library executes this Assembly, It redirects to JIT compilation for methods not included in the local image.

When you use ngen.exe to create a local image of an assembly, the output depends on the command line options you specify and some settings on the computer. These settings include:

• . NET Framework version.
• CPU type.
• The version of the operating system.
• The exact identifier of the Assembly (re-compilation will change the identifier ).
• The exact identifier of all the Assemblies referenced by the Assembly (the identifier is changed when the Assembly is recompiled ).
• Security factors.

Ngen.exe records this information when generating a local image. When you run the assembly, the runtime will look for the options that match the current environment of the computer and set the generated local image. If the runtime does not find a matching local image, it will be restored to the JIT compilation of the Assembly. The following changes to the computer settings and environment will invalidate the local image:

• . NET Framework version.

  If a patch, QFE, or update is applied to the. NET Framework, all local images manually created using ngen.exe will become invalid. These assemblies can still run, but the runtime does not load the corresponding local image of the Assembly. You must manually create a new local image for these sets.

  . NET Framework automatically creates a new local image for the. NET Framework library it has installed.

• CPU type.

  If you upgrade your computer's processor to a new processor series, all local images stored in the local image cache will become invalid.

• The version of the operating system.

  If the version of the operating system running on the computer changes, all local images stored in the local image cache will become invalid.

• The exact identifier of the Assembly.

  If you re-compile the assembly, the corresponding local image of the Assembly will become invalid.

• The exact identifier of any Assembly referenced by the Assembly.

  If you recompile any Assembly referenced by an assembly, the corresponding local image of the Assembly becomes invalid.

• Security factors.

  Change the computer security policy to restrict the permissions granted to an assembly. This will invalidate the locally compiled native image of the Assembly. Specifically, revoking any of the following permissions will invalidate the current local image of the Assembly:

  • The declarative inheritance permission required by the classes of the derived assembly.
  • The declarative link required by the method called by the Assembly.
  • SkipverificationPermission (if the Assembly contains any methods that cannot be verified ). For more information about this permission, see the securitypermissionattribute. skipverification attribute.
  • UnmanagedcodePermission (if the Assembly performs anyPinvokeCall ). For more information about this permission, see the securitypermissionattribute. unmanagedcode attribute.

  If ngen.exe is run on an assembly with code access security disabled, the ngen.exe native image generated by it becomes invalid when code access security is enabled. Note: by default, code access security is enabled.

  For details about how to manage code access security and how to use permissions in the Common Language Runtime Library, see code access security

  Note:In the public Language Runtime Library version 1.0, invalid local images are not automatically created or deleted. You must use ngen.exe to manually create or delete all local images.

If ngen.exe is used to generate a local image of the application during installation, you must specify the application file name and the fully-specified Assembly name of the. dll file referenced by the application during compilation. Provides the fully-specified Assembly name for the DLL file referenced by the application to enable ngen.exe to access the issuer policy file of the referenced assembly. In the future, if you update the DLL file and use the issuer policy to redirect, ngen.exe will apply the issuer policy.

By running ildasm.exe on an application and viewing its assembly list, you can obtain the fully-specified Assembly name to be used. This list shows the Assembly name, version, culture, and public key tag of the DLL file referenced by the application during compilation. For example, if you want to create a local image for an application named clientapp.exe, the application uses the mylibrary whose version is 1.0.0.0, the region is not a specific language, and the Public Key is marked as 0038abc9deabfle5. if the DLL file is compiled, use the commandNgen clientapp.exe "mylibrary, version = 1.0.0.0, culture = neutral, publickeytoken = 0038abc9deabfle5".

Note that the preceding example does not generate a local image of the Assembly referenced by mylibrary. dll. To determine the exact name of the Assembly referenced by mylibrary. dll, run ildasm.exe on mylibrary. dll. For example. run ildasm.exe on the DLL, and make sure that it references the MySQL math whose version is 1.0.0.0, the region is not a specific language, and the Public Key is marked as 0039def8abcbste7. DLL. Use the following command to generate a local image for the directory tree referenced by the entire assembly of 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 ".
 

For more information about this format, see the "example" section after this topic.

The uninstall process of the application should use/Delete[Assemblyname|Assemblypath] Option to remove the local image created when the application is installed. RequiredAssemblynameOrAssemblypathThe parameter specifies the specific local image to be deleted. Specify/Delete *All local images in the local image cache will be removed; Specify/DeleteIf the parameter is not specified, an error occurs.

Example

The following command isClientapp.exeGenerate a local image. If the application has a configuration file, ngen.exe will use it. This tool does notClientapp.exeAny DLL referenced to generate a local image.

 
Ngen clientapp.exe
 

IfClientapp.exeDirectly reference two DLL (Mylibone. dllAndMylibtwo. dllNgen.exe must provide the fully-specified Assembly names for these DLL files to generate a local image for them. PairClientapp.exeRun ildasm.exe to determine the name of the fully-specified assembly of the referenced DLL. In this example,Mylibone. dllAndMylibtwo. dllThe fully-specified Assembly name of is"Mylibone, version = 1.0.0.0, culture = neutral, publickeytoken = 0038abc9deabfle5"And"Mylibtwo, version = 1.0.0.0, culture = neutral, publickeytoken = 0038abc9deabfle5". Use the following command to generateClientapp.exe,Mylibone. dllAndMylibtwo. dll. IfClientapp.exeIf the configuration file exists, ngen.exe will use it. IfMylibone. dllOrMylibtwo. dllIf the issuer policy file 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 fileMylibone. dllAndMylibtwo. dllOther assembly can be referenced. To determine the fully-specified Assembly name of the referenced assembly, goMylibone. dllAndMylibtwo. dllRun ildasm.exe. In this example, assume thatMylibone. dllNo other assembly is referenced,Mylibtwo. dllReference"Mymath, version = 1.0.0.0, culture = neutral, publickeytoken = 0039def8abcbste7". With this information, the following command generates a local image for the entire Assembly reference directory tree of the application.

 
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 generatesMyassembly.exe.

 
Ngen c: \ myfiles \ myassembly.exe
 

The following command generates a local image of mylibrary. dll in the specified path.

 
Ngen c: \ myfiles \ mylibrary. dll
 

Ngen.exe searches for the local image cache and deletes the Assembly specified by some assembly names. The following command deletesMyassemblyName of all local images.

 
Ngen/delete myassembly
 

The following command deletes a local image with the specified Assembly nameMyassembly.

 
Ngen/Delete "myassembly, version = 1.0.0.0, culture = neutral, publickeytoken = 0038abc9deabfle5"
 

The following command displays all local images in the local image cache.

 
Ngen/show
 

The following command shows the name in the local image CacheMyassemblyAll local images.

 
Ngen/show myassembly
 

The following command shows the name in the local image CacheMyassemblyAnd all local images whose version is 1.0.

 
Ngen/Show "myassembly, version = 1.0.0.0"