Skip to content

Commit

Permalink
Add multilevel lookup breaking change (#28965)
Browse files Browse the repository at this point in the history
  • Loading branch information
gewarren authored Apr 18, 2022
1 parent 2b437b5 commit fbc2ed7
Show file tree
Hide file tree
Showing 4 changed files with 72 additions and 1 deletion.
6 changes: 6 additions & 0 deletions docs/core/compatibility/7.0.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,12 @@ If you're migrating an app to .NET 7, the breaking changes listed here might aff
| [SerializationFormat.Binary is obsolete](core-libraries/7.0/serializationformat-binary.md) ||| Preview 2 |
| [Validate CompressionLevel for BrotliStream](core-libraries/7.0/compressionlevel-validation.md) || ✔️ | Preview 1 |

## Deployment

| Title | Binary compatible | Source compatible | Introduced |
| - | :-: | :-: | - |
| [Multi-level lookup is disabled](deployment/7.0/multilevel-lookup.md) || ✔️ | Preview 4 |

## Networking

| Title | Binary compatible | Source compatible | Introduced |
Expand Down
52 changes: 52 additions & 0 deletions docs/core/compatibility/deployment/7.0/multilevel-lookup.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
---
title: "Breaking change: Multi-level lookup is disabled"
description: Learn about the .NET 7 breaking change in deployment where multi-level lookup is disabled.
ms.date: 04/08/2022
---
# Multi-level lookup is disabled

On Windows, framework-dependent .NET applications no longer search for frameworks in multiple install locations.

## Previous behavior

In previous versions, a framework-dependent .NET application searched for frameworks in multiple install locations on Windows. The locations were:

- When running the application through [dotnet](../../../tools/dotnet.md), subdirectories relative to the `dotnet` executable.
- When running the application through its executable (`apphost`), the location specified by the value of the `DOTNET_ROOT` environment variable (if set).
- The globally registered install location in **HKLM\SOFTWARE\dotnet\Setup\InstalledVersions\<arch>\InstallLocation** (if set).
- The 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

Applications that target .NET 7 or a later version only look for frameworks in one location, which is the first location where a .NET installation is found. When running an application through [dotnet](../../../tools/dotnet.md), frameworks are only searched for in subdirectories relative to the `dotnet` executable. When running an application through its executable (`apphost`), frameworks are only searched for in the first of the following locations where .NET is found:

- The location specified by the value of the `DOTNET_ROOT` environment variable (if set).
- The globally registered install location in **HKLM\SOFTWARE\dotnet\Setup\InstalledVersions\<arch>\InstallLocation** (if set).
- The default install location of *%ProgramFiles%\dotnet* (or *%ProgramFiles(x86)%\dotnet* for 32-bit processes on 64-bit Windows).

## Version introduced

.NET 7 Preview 4

## Type of breaking change

This change can affect [binary compatibility](../../categories.md#binary-compatibility).

## Reason for change

There've been numerous issues caused by multi-level lookup:

- Confusion for users: application can pick a global or 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 and tests.
- Performance issues.

## Recommended action

Make sure the required version of .NET is installed at the single .NET install location. The error messages that are emitted on failure to launch include the expected location.

## Affected APIs

None.
10 changes: 10 additions & 0 deletions docs/core/compatibility/toc.yml
Original file line number Diff line number Diff line change
Expand Up @@ -51,6 +51,10 @@ items:
href: core-libraries/7.0/serializationformat-binary.md
- name: Validate CompressionLevel for BrotliStream
href: core-libraries/7.0/compressionlevel-validation.md
- name: Deployment
items:
- name: Multi-level lookup is disabled
href: deployment/7.0/multilevel-lookup.md
- name: Networking
items:
- name: AllowRenegotiation default is false
Expand Down Expand Up @@ -849,6 +853,12 @@ items:
href: cryptography/5.0/tripledes-default-feedback-size-change.md
- name: .NET Core 2.1-3.0
href: cryptography.md
- name: Deployment
items:
- name: .NET 7
items:
- name: Multi-level lookup is disabled
href: deployment/7.0/multilevel-lookup.md
- name: Entity Framework Core
items:
- name: EF Core 6
Expand Down
5 changes: 4 additions & 1 deletion docs/core/tools/dotnet-environment-variables.md
Original file line number Diff line number Diff line change
Expand Up @@ -214,7 +214,10 @@ If `DOTNET_SKIP_FIRST_TIME_EXPERIENCE` is set to `true`, the `NuGetFallbackFolde

### `DOTNET_MULTILEVEL_LOOKUP`

Specifies whether .NET runtime, shared framework, or SDK are resolved from the global location. If not set, it defaults to 1 (logical `true`). Set to 0 (logical `false`) to not resolve from the global location and have isolated .NET installations. For more information about multi-level lookup, see [Multi-level SharedFX Lookup](https://github.com/dotnet/core-setup/blob/master/Documentation/design-docs/multilevel-sharedfx-lookup.md).
Specifies whether the .NET runtime, shared framework, or SDK are resolved from the global location. If not set, it defaults to 1 (logical `true`). Set the value to 0 (logical `false`) to not resolve from the global location and have isolated .NET installations. For more information about multi-level lookup, see [Multi-level SharedFX Lookup](https://github.com/dotnet/core-setup/blob/master/Documentation/design-docs/multilevel-sharedfx-lookup.md).

> [!NOTE]
> This environment variable only applies to applications that target .NET 6 and earlier versions. Starting in .NET 7, .NET only looks for frameworks in one location. For more information, see [Multi-level lookup is disabled](../compatibility/deployment/7.0/multilevel-lookup.md).
### `DOTNET_ROLL_FORWARD`

Expand Down

0 comments on commit fbc2ed7

Please sign in to comment.