[Breaking change]: Multi-level lookup behavior is being disabled

[elinor-fung]

Description

On Windows, framework-dependent .NET applications would search for frameworks in multiple install locations by default. In .NET 7, this behavior is disabled.

Runtime change: dotnet/runtime#67022

Version

.NET 7 Preview 4

Previous behavior

A framework-dependent .NET application could search for frameworks in multiple install locations:

1. Subdirectories relative to:

   • dotnet executable when running the application through dotnet
   • DOTNET_ROOT environment variable (if set) when running the application through its executable (apphost)

2. Globally registered install location (if set) in HKLM\SOFTWARE\dotnet\Setup\InstalledVersions\<arch>\InstallLocation.

3. Default install location of %ProgramFiles%\dotnet (or %ProgramFiles(x86)%\dotnet for 32-bit processes on 64-bit Windows).

This multi-level lookup behavior was enabled by default but could be disabled by setting the environment variable DOTNET_MULTILEVEL_LOOKUP=0.

New behavior

An application targeting .NET 7 or above will only look in one location - the first location where a .NET installation is found. When running an application through dotnet, frameworks are only searched for in subdirectories relative to dotnet. When running an application through its executable (apphost), frameworks are only searched for in the first of the locations listed in the previous behavior section where .NET is found.

Applications targeting .NET 6 or below are unaffected.

Type of breaking change

• Binary incompatible: Existing binaries may encounter a breaking change in behavior, such as failure to load/execute or different run-time behavior.
• Source incompatible: Source code may encounter a breaking change in behavior when targeting the new runtime/component/SDK, such as compile errors or different run-time behavior.

Reason for change

There has been a lot of feedback around issues caused by multi-level lookup:

• Confusion for users: application can pick a global/default install location despite running .NET from a private install
• Inconsistency between platforms (Windows versus non-Windows)
• Behavior breaks, often in automated systems: a new global .NET install can affect otherwise isolated builds/tests.
• Performance issues

Recommended action

Make sure the required version of .NET is installed at the single .NET install location. Error messages on failure to launch include the expected location.

Feature area

Deployment

Affected APIs

No response