Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add multilevel lookup breaking change #28965

Merged
merged 3 commits into from
Apr 18, 2022
Merged

Add multilevel lookup breaking change #28965

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
1953f6b
add multilevel breaking change
gewarren Apr 8, 2022
f3e4ac9
add note about environment variable
gewarren Apr 18, 2022
67af04c
respond to feedback
gewarren Apr 18, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions docs/core/compatibility/7.0.md
View file
Open in desktop
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
48 changes: 48 additions & 0 deletions docs/core/compatibility/deployment/7.0/multilevel-lookup.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
---
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:

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

## 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 locations listed in the [previous behavior section](#previous-behavior) where .NET is found.
gewarren marked this conversation as resolved.
Show resolved Hide resolved

## 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
View file
Open in desktop
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