Add multilevel lookup breaking change (#28965)

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 |

docs/core/compatibility/deployment/7.0/multilevel-lookup.md

@@ -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.

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

docs/core/tools/dotnet-environment-variables.md

@@ -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`