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

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

* lint fix

* Review feedback from @am11

* Review feedback from @jkotas

* period

* Apply suggestions from code review

Co-authored-by: Aaron Robinson <[email protected]>
Co-authored-by: Adeel Mujahid <[email protected]>
Co-authored-by: Jan Kotas <[email protected]>

* type of change

* another fix

* Apply suggestions from code review

Co-authored-by: Jan Kotas <[email protected]>

* indent

* fixed xrefs

---------

Co-authored-by: Aaron Robinson <[email protected]>
Co-authored-by: Adeel Mujahid <[email protected]>
Co-authored-by: Jan Kotas <[email protected]>

Author: 4 people

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)              | Behavioral change   |
 
 ## 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 [behavioral change](../../categories.md#behavioral-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?displayProperty=fullName>
+  - [System.Runtime.Loader.AssemblyLoadContext.LoadUnmanagedDll](/dotnet/api/system.runtime.loader.assemblyloadcontext.loadunmanageddll)
+  - <xref:System.Runtime.InteropServices.NativeLibrary.SetDllImportResolver(System.Reflection.Assembly,System.Runtime.InteropServices.DllImportResolver)?displayProperty=fullName>
+  - <xref:System.Runtime.InteropServices.NativeLibrary.Load*?displayProperty=fullName>
+- 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