[Breaking change]: Specifying DllImportSearchPath.AssemblyDirectory by itself only searches in the assembly directory

docs/core/compatibility/10.0.md

@@ -48,6 +48,12 @@ If you're migrating an app to .NET 10, the breaking changes listed here might af
 | [X509Certificate and PublicKey key parameters can be null](cryptography/10.0/x509-publickey-null.md)     | Behavioral/source incompatible change | Preview 3          |
 | [Environment variable renamed to DOTNET_OPENSSL_VERSION_OVERRIDE](cryptography/10.0/version-override.md) | Behavioral change                     | Preview 1          |
 
+## Interop
+
+| Title                                                                                                                              | Type of change    | Introduced version |
+|------------------------------------------------------------------------------------------------------------------------------------|-------------------|--------------------|
+| [Specifying DllImportSearchPath.AssemblyDirectory only searches the assembly directory](interop/10.0/search-assembly-directory.md) | Behavioral change | Preview 5          |
+
 ## Networking
 
 | Title                                                                                                            | Type of change    | Introduced version |

docs/core/compatibility/interop/10.0/search-assembly-directory.md

@@ -0,0 +1,59 @@
+---
+title: "Breaking change - Specifying DllImportSearchPath.AssemblyDirectory only searches the assembly directory"
+description: "Learn about the breaking change in .NET 10 Preview 5 where specifying DllImportSearchPath.AssemblyDirectory as the only search flag restricts the search to the assembly directory."
+ms.date: 5/9/2025
+ai-usage: ai-assisted
+ms.custom: https://github.com/dotnet/docs/issues/45911
+---
+
+# Specifying DllImportSearchPath.AssemblyDirectory only searches the assembly directory
+
+Starting in .NET 10, if you specify <xref:System.Runtime.InteropServices.DllImportSearchPath.AssemblyDirectory?displayProperty=nameWithType> as the only search flag, the runtime searches exclusively in the assembly directory. This change affects the behavior of P/Invokes and the <xref:System.Runtime.InteropServices.NativeLibrary> class.
+
+## Version introduced
+
+.NET 10 Preview 5
+
+## Previous behavior
+
+When <xref:System.Runtime.InteropServices.DllImportSearchPath.AssemblyDirectory?displayProperty=nameWithType> was specified as the only search flag, the runtime searched the assembly directory first. If the library was not found, it fell back to the operating system's default library search behavior.
+
+Example:
+
+```csharp
+[DllImport("example.dll", DllImportSearchPath = DllImportSearchPath.AssemblyDirectory)]
+public static extern void ExampleMethod();
+```
+
+In this case, the runtime would search the assembly directory and then fall back to the OS search paths.
+
+## New behavior
+
+When <xref:System.Runtime.InteropServices.DllImportSearchPath.AssemblyDirectory?displayProperty=nameWithType> is specified as the only search flag, the runtime searches only in the assembly directory. It does not fall back to the operating system's default library search behavior.
+
+The previous code example would now only search the assembly directory for *example.dll*. If the library is not found there, a <xref:System.DllNotFoundException> will be thrown.
+
+## Type of breaking change
+
+This is a [behavioral change](../../categories.md#behavioral-change).
+
+## Reason for change
+
+The fallback behavior when specifying <xref:System.Runtime.InteropServices.DllImportSearchPath.AssemblyDirectory?displayProperty=nameWithType> caused confusion and was inconsistent with the design of search flags. This change ensures clarity and consistency in behavior.
+
+## Recommended action
+
+If fallback behavior is required, avoid specifying an explicit <xref:System.Runtime.InteropServices.DllImportSearchPath>. By default, when no flags are specified, the runtime searches the assembly directory and then falls back to the operating system's default library search behavior.
+
+Example:
+
+```csharp
+[DllImport("example.dll")]
+public static extern void ExampleMethod();
+```
+
+## Affected APIs
+
+- P/Invokes using <xref:System.Runtime.InteropServices.DefaultDllImportSearchPathsAttribute>
+- <xref:System.Runtime.InteropServices.NativeLibrary.Load*?displayProperty=fullName>
+- <xref:System.Runtime.InteropServices.NativeLibrary.TryLoad*?displayProperty=fullName>

docs/core/compatibility/toc.yml

@@ -42,6 +42,10 @@ items:
             items:
               - name: Environment variable renamed to DOTNET_ICU_VERSION_OVERRIDE
                 href: globalization/10.0/version-override.md
+          - name: Interop
+            items:
+              - name: Specifying DllImportSearchPath.AssemblyDirectory only searches the assembly directory
+                href: interop/10.0/search-assembly-directory.md
           - name: Networking
             items:
               - name: Streaming HTTP responses enabled by default in browser HTTP clients
@@ -1808,6 +1812,10 @@ items:
             href: globalization.md
       - name: Interop
         items:
+          - name: .NET 10
+            items:
+              - name: Specifying DllImportSearchPath.AssemblyDirectory only searches the assembly directory
+                href: interop/10.0/search-assembly-directory.md
           - name: .NET 9
             items:
               - name: CET supported by default