[Breaking change]: On Windows in .NET 9, the assembly load directory resolves through symbolic links (#45627)

* [Breaking change]: On Windows in .NET 9, the assembly load directory resolves through symbolic links
Fixes #45584

* ToC and .NET 9 overview

* Fix contraction in assembly load directory documentation

Author: Cam Soper

docs/core/compatibility/9.0.md

@@ -2,7 +2,7 @@
 title: Breaking changes in .NET 9
 titleSuffix: ""
 description: Navigate to the breaking changes in .NET 9.
-ms.date: 03/26/2025
+ms.date: 04/03/2025
 no-loc: [Blazor, Razor, Kestrel]
 ---
 # Breaking changes in .NET 9
@@ -68,9 +68,10 @@ If you're migrating an app to .NET 9, the breaking changes listed here might aff
 
 ## Deployment
 
-| Title                                                                                               | Type of change      | Introduced version |
-|-----------------------------------------------------------------------------------------------------|---------------------|--------------------|
-| [Deprecated desktop Windows/macOS/Linux MonoVM runtime packages](deployment/9.0/monovm-packages.md) | Source incompatible | Preview 7          |
+| Title                                                                                                           | Type of change      | Introduced version |
+|-----------------------------------------------------------------------------------------------------------------|---------------------|--------------------|
+| [Deprecated desktop Windows/macOS/Linux MonoVM runtime packages](deployment/9.0/monovm-packages.md)             | Source incompatible | Preview 7          |
+| [Assembly load directory resolves through symbolic links on Windows](deployment/9.0/assembly-load-directory.md) | Behavioral change   | GA                 |
 
 ## Interop
 

docs/core/compatibility/deployment/9.0/assembly-load-directory.md

@@ -0,0 +1,73 @@
+---
+title: "Breaking change - Assembly load directory resolves through symbolic links on Windows"
+description: "Learn about the breaking change in .NET 9 where the assembly load directory resolves through symbolic links."
+ms.date: 4/3/2025
+ai-usage: ai-assisted
+ms.custom: https://github.com/dotnet/docs/issues/45584
+---
+
+# Assembly load directory resolves through symbolic links on Windows
+
+Starting in .NET 9, the .NET host resolves symbolic links before determining the assembly load directory when running on Windows.
+
+## Version introduced
+
+.NET 9
+
+## Previous behavior
+
+The .NET host didn't resolve symbolic links before calculating load paths. Assembly loads were resolved relative to the symbolic link itself, not the destination of the link.
+
+For example, if an application was laid out as follows:
+
+```
+/myapp/
+  myapp.exe
+  myapp.dll
+```
+
+And a symbolic link was created in another directory:
+
+```
+otherdir/
+  myapp.exe -> /myapp/myapp.exe
+```
+
+Executing `otherdir/myapp.exe` would resolve loads relative to `otherdir/`, not `/myapp/`.
+
+## New behavior
+
+The .NET host now resolves the destination of a symbolic link before determining the assembly load directory. Assembly loads are resolved relative to the resolved location of the host file.
+
+Using the same example:
+
+```
+/myapp/
+  myapp.exe
+  myapp.dll
+```
+
+With a symbolic link:
+
+```
+otherdir/
+  myapp.exe -> /myapp/myapp.exe
+```
+
+Executing `otherdir/myapp.exe` resolves loads relative to `/myapp/`. Files in `otherdir/` are not considered.
+
+## Type of breaking change
+
+This is a [behavioral change](../../categories.md#behavioral-change).
+
+## Reason for change
+
+The previous behavior on Windows was undocumented, inconsistent with non-Windows implementations, and prevented supported use of symbolic links to the .NET host. This change ensures consistent behavior and enables scenarios where symbolic links to the .NET host are used properly.
+
+## Recommended action
+
+If your application relied on the previous behavior, ensure that all relevant binaries are located in the directory behind the symbolic link, rather than next to it. Avoid constructing a file layout that depends on the symbolic link's location.
+
+## Affected APIs
+
+None.

docs/core/compatibility/toc.yml

@@ -140,6 +140,8 @@ items:
             items:
               - name: Deprecated desktop Windows/macOS/Linux MonoVM runtime packages
                 href: deployment/9.0/monovm-packages.md
+              - name: Assembly load directory resolves through symbolic links on Windows
+                href: deployment/9.0/assembly-load-directory.md
           - name: Entity Framework Core
             href: /ef/core/what-is-new/ef-core-9.0/breaking-changes?toc=/dotnet/core/compatibility/toc.json&bc=/dotnet/breadcrumb/toc.json
           - name: Interop
@@ -1678,6 +1680,8 @@ items:
             items:
               - name: Deprecated desktop Windows/macOS/Linux MonoVM runtime packages
                 href: deployment/9.0/monovm-packages.md
+              - name: Assembly load directory resolves through symbolic links on Windows
+                href: deployment/9.0/assembly-load-directory.md
           - name: .NET 8
             items:
               - name: Host determines RID-specific assets