From 1953f6bec80cda87cba923e41d38e078cc76ee86 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Fri, 8 Apr 2022 16:11:28 -0700 Subject: [PATCH 1/3] add multilevel breaking change --- docs/core/compatibility/7.0.md | 6 +++ .../deployment/7.0/multilevel-lookup.md | 48 +++++++++++++++++++ docs/core/compatibility/toc.yml | 10 ++++ 3 files changed, 64 insertions(+) create mode 100644 docs/core/compatibility/deployment/7.0/multilevel-lookup.md diff --git a/docs/core/compatibility/7.0.md b/docs/core/compatibility/7.0.md index ba718abb29915..90713ef94ba11 100644 --- a/docs/core/compatibility/7.0.md +++ b/docs/core/compatibility/7.0.md @@ -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 | diff --git a/docs/core/compatibility/deployment/7.0/multilevel-lookup.md b/docs/core/compatibility/deployment/7.0/multilevel-lookup.md new file mode 100644 index 0000000000000..ae468a84f62bc --- /dev/null +++ b/docs/core/compatibility/deployment/7.0/multilevel-lookup.md @@ -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\\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`. + +## 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. + +## 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. diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml index b7d670c842980..62f491ec757d8 100644 --- a/docs/core/compatibility/toc.yml +++ b/docs/core/compatibility/toc.yml @@ -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 @@ -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 From f3e4ac955f2bd5c54a183ba759e58048d53171d0 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Mon, 18 Apr 2022 11:42:09 -0700 Subject: [PATCH 2/3] add note about environment variable --- docs/core/compatibility/deployment/7.0/multilevel-lookup.md | 2 +- docs/core/tools/dotnet-environment-variables.md | 5 ++++- 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/core/compatibility/deployment/7.0/multilevel-lookup.md b/docs/core/compatibility/deployment/7.0/multilevel-lookup.md index ae468a84f62bc..b6e493a2b315e 100644 --- a/docs/core/compatibility/deployment/7.0/multilevel-lookup.md +++ b/docs/core/compatibility/deployment/7.0/multilevel-lookup.md @@ -9,7 +9,7 @@ On Windows, framework-dependent .NET applications no longer search for framework ## Previous behavior -In previous versions, a framework-dependent .NET application searched for frameworks in multiple install locations on Windows: +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 `DOTNET_ROOT` environment variable (if set). diff --git a/docs/core/tools/dotnet-environment-variables.md b/docs/core/tools/dotnet-environment-variables.md index 5b1c1264de83e..a1a6312696200 100644 --- a/docs/core/tools/dotnet-environment-variables.md +++ b/docs/core/tools/dotnet-environment-variables.md @@ -208,7 +208,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` From 67af04c81702d032e4e9bfca47822bf072c6d829 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Mon, 18 Apr 2022 14:30:26 -0700 Subject: [PATCH 3/3] respond to feedback --- .../compatibility/deployment/7.0/multilevel-lookup.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/docs/core/compatibility/deployment/7.0/multilevel-lookup.md b/docs/core/compatibility/deployment/7.0/multilevel-lookup.md index b6e493a2b315e..172eccc5e1f5d 100644 --- a/docs/core/compatibility/deployment/7.0/multilevel-lookup.md +++ b/docs/core/compatibility/deployment/7.0/multilevel-lookup.md @@ -12,15 +12,19 @@ On Windows, framework-dependent .NET applications no longer search for framework 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 `DOTNET_ROOT` environment variable (if set). -- The globally registered install location (if set) in **HKLM\SOFTWARE\dotnet\Setup\InstalledVersions\\InstallLocation**. +- 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\\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 locations listed in the [previous behavior section](#previous-behavior) where .NET is found. +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\\InstallLocation** (if set). +- The default install location of *%ProgramFiles%\dotnet* (or *%ProgramFiles(x86)%\dotnet* for 32-bit processes on 64-bit Windows). ## Version introduced