Determining Which Version of the Runtime to Load

  • Article

The common language runtime uses the following information to determine which version of the runtime to load for an application:

  • The runtime versions that are available.
  • The runtime versions that an application supports.

Available Runtime Versions

The runtime determines the available runtime versions by enumerating the keys and values in the registry under HKLM\SOFTWARE\Microsoft\.NETFramework\policy. Each key identifies the major and minor version of the runtime. The values under each major and minor key identify the build number. For example, the key HKLM\SOFTWARE\Microsoft\.NETFramework\policy\v1.0 with a value of 3705 indicates that version 1.0.3705 of the .NET Framework is installed.

A directory with the same version number as specified in the registry must also exist under the .NET Framework installation root. The directory names are preceded with the letter v. For example, version 1.0.3705 of the .NET Framework would be installed in <InstallRoot>\v1.0.3705.

Supported Runtime Versions

The runtime uses the application configuration file and the portable executable (PE) file header to determine which version of the runtime an application supports. If no application configuration file is present, the runtime loads the runtime version specified in the application's PE file header, if that version is available.

If an application configuration file is present, the runtime determines the appropriate runtime version to load based on the results of the following process:

  1. The runtime examines the <supportedRuntime> element in the application configuration file. If one or more of the supported runtime versions specified in the <supportedRuntime> element are present, the runtime loads the runtime version specified by the first <supportedRuntime> element. If this version is not available, the runtime examines the next <supportedRuntime> element and attempts to load the runtime version specified. If this runtime version is not available, subsequent <supportedRuntime> elements are examined. If none of the supported runtime versions are available, the runtime fails to load a runtime version and displays a message to the user (see step 4).

  2. If no <supportedRuntime> element is present, the runtime examines the <requiredRuntime> element in the application configuration file. This element is used only for runtime version 1.0 applications. If the runtime version specified by the <requiredRuntime> element is present, the runtime loads it. If the specified version is not available, the runtime fails to load and displays a message to the user (see step 4). If the application configuration file has no <requiredRuntime> element, the process continues to step 3.

  3. The runtime reads the PE file header of the application's executable file. If the runtime version specified by the PE file header is available, the runtime loads that version. If the runtime version specified is not available, the runtime searches for a runtime version determined by Microsoft to be compatible with the runtime version in the PE header. If that version is not found, the process continues to step 4.

  4. The runtime displays a message stating that the runtime version supported by the application is unavailable. The runtime is not loaded.

    Note   You can suppress the display of this message using the NoGuiFromShim value under the registry key HKLM\Software\Microsoft\.NETFramework or using the environment variable COMPLUS_NoGuiFromShim. For example, you can suppress the message for applications that do no typically interact with the user, such as unattended installations or Windows services. When this message display is suppressed, the runtime writes a message to the event log. Set the registry value NoGuiFromShim to 1 to suppress this message for all applications on a computer. Alternately, set the COMPLUS_NoGuiFromShim environment variable to 1 to suppress the message for applications running in a particular user context.

Note   After a runtime version is loaded, assembly binding redirects can specify that a different version of an individual .NET Framework assembly be loaded. These binding redirects affect only the specific assembly that is redirected.

See Also

Assembly Binding Redirection | Locating Runtime Version Information | Configuring Assembly Binding Redirection | Side-by-Side Execution Fundamentals