[Breaking change]: .NET Linux applications do not look in netcoredeps sub-directory for native libraries

docs/core/compatibility/8.0.md

@@ -2,7 +2,7 @@
 title: Breaking changes in .NET 8
 titleSuffix: ""
 description: Navigate to the breaking changes in .NET 8.
-ms.date: 12/05/2023
+ms.date: 04/10/2025
 no-loc: [Blazor, Razor, Kestrel]
 ---
 # Breaking changes in .NET 8
@@ -102,13 +102,14 @@ If you're migrating an app to .NET 8, the breaking changes listed here might aff
 
 ## Interop
 
-| Title                                                                                             | Type of change      |
-| ------------------------------------------------------------------------------------------------- | ------------------- |
-| [CreateObjectFlags.Unwrap only unwraps on target instance](interop/8.0/comwrappers-unwrap.md)     | Behavioral change   |
-| [Custom marshallers require additional members](interop/8.0/marshal-modes.md)                     | Source incompatible |
-| [IDispatchImplAttribute API is removed](interop/8.0/idispatchimplattribute-removed.md)            | Binary incompatible   |
-| [JSFunctionBinding implicit public default constructor removed](interop/8.0/jsfunctionbinding-constructor.md) | Binary incompatible   |
-| [SafeHandle types must have public constructor](interop/8.0/safehandle-constructor.md)            | Source incompatible |
+| Title                                                                                                         | Type of change      |
+|---------------------------------------------------------------------------------------------------------------|---------------------|
+| [CreateObjectFlags.Unwrap only unwraps on target instance](interop/8.0/comwrappers-unwrap.md)                 | Behavioral change   |
+| [Custom marshallers require additional members](interop/8.0/marshal-modes.md)                                 | Source incompatible |
+| [IDispatchImplAttribute API is removed](interop/8.0/idispatchimplattribute-removed.md)                        | Binary incompatible |
+| [JSFunctionBinding implicit public default constructor removed](interop/8.0/jsfunctionbinding-constructor.md) | Binary incompatible |
+| [SafeHandle types must have public constructor](interop/8.0/safehandle-constructor.md)                        | Source incompatible |
+| [Linux native library resolution no longer uses `netcoredeps`](interop/8.0/linux-netcoredeps.md)              | Source incompatible |
 
 ## Networking
 

docs/core/compatibility/interop/8.0/linux-netcoredeps.md

@@ -0,0 +1,49 @@
+---
+title: "Breaking change - Linux native library resolution no longer uses `netcoredeps`"
+description: "Learn about the breaking change in .NET 8 where Linux applications no longer search the `netcoredeps` subdirectory for native libraries."
+ms.date: 4/10/2025
+ai-usage: ai-assisted
+ms.custom: https://github.com/dotnet/docs/issues/45777
+---
+
+# Linux native library resolution no longer uses `netcoredeps`
+
+Starting in .NET 8, Linux applications no longer search the `netcoredeps` subdirectory for native libraries.
+
+## Version introduced
+
+.NET 8
+
+## Previous behavior
+
+In earlier versions of .NET, Linux applications searched for native libraries in a `netcoredeps` subdirectory located next to the application executable. This behavior applied to all native library loads, including user-defined platform invokes (p/invokes).
+
+## New behavior
+
+In .NET 8 and later, Linux applications no longer search the `netcoredeps` subdirectory for native libraries. Native library resolution now follows standard mechanisms without relying on this subdirectory.
+
+## Type of breaking change
+
+This is a [source incompatible](../../categories.md#source-compatibility) change.
+
+## Reason for change
+
+The `netcoredeps` behavior was originally introduced to handle complex dependencies on third-party libraries in earlier .NET versions. .NET 8+ no longer requires this behavior due to improved dependency handling. Additionally, the mechanism isn't aligned with recommended practices for ELF platforms.
+
+For more information, see [GitHub issue #114393](https://github.com/dotnet/runtime/issues/114393).
+
+## Recommended action
+
+If your application relied on the `netcoredeps` subdirectory for p/invokes or custom native library resolution, use the following alternatives:
+
+- Implement a custom resolution mechanism using one of the following:
+    - <xref:System.Runtime.Loader.AssemblyLoadContext.ResolvingUnmanagedDll>
+    - <xref:System.Runtime.InteropServices.NativeLibrary.SetDllImportResolver>
+    - <xref:System.Runtime.InteropServices.NativeLibrary.Load>
+    - <xref:System.Runtime.InteropServices.NativeLibrary.SetDllImportResolver>
+- If an `RPATH` is required in your deployment, modify the ELF file explicitly using the `patchelf` utility.
+
+## Affected APIs
+
+- `DllImport`
+- <xref:System.Runtime.InteropServices.NativeLibrary.Load*?displayProperty=fullName>

docs/core/compatibility/toc.yml

@@ -362,6 +362,8 @@ items:
                 href: interop/8.0/jsfunctionbinding-constructor.md
               - name: SafeHandle types must have public constructor
                 href: interop/8.0/safehandle-constructor.md
+              - name: Linux native library resolution no longer uses `netcoredeps`
+                href: interop/8.0/linux-netcoredeps.md
           - name: Networking
             items:
               - name: SendFile throws NotSupportedException for connectionless sockets
@@ -1818,6 +1820,8 @@ items:
                 href: interop/8.0/jsfunctionbinding-constructor.md
               - name: SafeHandle types must have public constructor
                 href: interop/8.0/safehandle-constructor.md
+              - name: Linux native library resolution no longer uses `netcoredeps`
+                href: interop/8.0/linux-netcoredeps.md
           - name: .NET 7
             items:
               - name: RuntimeInformation.OSArchitecture under emulation