From 2ab16e0fae6b3fc7f894537e8658b022c8794ab0 Mon Sep 17 00:00:00 2001 From: Cam Date: Fri, 9 May 2025 22:51:24 +0000 Subject: [PATCH 1/4] [Breaking change]: Specifying DllImportSearchPath.AssemblyDirectory by itself only searches in the assembly directory Fixes #45911 --- docs/core/compatibility/10.0.md | 6 ++ .../interop/10.0/search-assembly-directory.md | 59 +++++++++++++++++++ docs/core/compatibility/toc.yml | 8 +++ 3 files changed, 73 insertions(+) create mode 100644 docs/core/compatibility/interop/10.0/search-assembly-directory.md diff --git a/docs/core/compatibility/10.0.md b/docs/core/compatibility/10.0.md index e9ac7d2247509..e055372443f5a 100644 --- a/docs/core/compatibility/10.0.md +++ b/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 | diff --git a/docs/core/compatibility/interop/10.0/search-assembly-directory.md b/docs/core/compatibility/interop/10.0/search-assembly-directory.md new file mode 100644 index 0000000000000..576011a365923 --- /dev/null +++ b/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 + +In .NET 10 Preview 5, specifying `DllImportSearchPath.AssemblyDirectory` as the only search flag now restricts the runtime to search exclusively in the assembly directory. This change affects the behavior of P/Invokes and the `NativeLibrary` class. + +## Version introduced + +.NET 10 Preview 5 + +## Previous behavior + +When `DllImportSearchPath.AssemblyDirectory` 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 `DllImportSearchPath.AssemblyDirectory` 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 `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 `DllImportSearchPath.AssemblyDirectory` 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 `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 [`DefaultDllImportSearchPaths`](https://learn.microsoft.com/dotnet/api/system.runtime.interopservices.defaultdllimportsearchpathsattribute) +- [`NativeLibrary.Load`](https://learn.microsoft.com/dotnet/api/system.runtime.interopservices.nativelibrary.load#system-runtime-interopservices-nativelibrary-load(system-string-system-reflection-assembly-system-nullable((system-runtime-interopservices-dllimportsearchpath)))) +- [`NativeLibrary.TryLoad`](https://learn.microsoft.com/dotnet/api/system.runtime.interopservices.nativelibrary.tryload#system-runtime-interopservices-nativelibrary-tryload(system-string-system-reflection-assembly-system-nullable((system-runtime-interopservices-dllimportsearchpath))-system-intptr@)) diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml index 9a68a1eeca6c4..4d0bce476f8ee 100644 --- a/docs/core/compatibility/toc.yml +++ b/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 From e74996b5ea3ffcf394e095808ca3c16ec18cd2e5 Mon Sep 17 00:00:00 2001 From: Cam Date: Fri, 9 May 2025 23:31:27 +0000 Subject: [PATCH 2/4] Xrefs --- .../interop/10.0/search-assembly-directory.md | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/docs/core/compatibility/interop/10.0/search-assembly-directory.md b/docs/core/compatibility/interop/10.0/search-assembly-directory.md index 576011a365923..b652ff538f24e 100644 --- a/docs/core/compatibility/interop/10.0/search-assembly-directory.md +++ b/docs/core/compatibility/interop/10.0/search-assembly-directory.md @@ -8,7 +8,7 @@ ms.custom: https://github.com/dotnet/docs/issues/45911 # Specifying DllImportSearchPath.AssemblyDirectory only searches the assembly directory -In .NET 10 Preview 5, specifying `DllImportSearchPath.AssemblyDirectory` as the only search flag now restricts the runtime to search exclusively in the assembly directory. This change affects the behavior of P/Invokes and the `NativeLibrary` class. +In .NET 10 Preview 5, specifying as the only search flag now restricts the runtime to search exclusively in the assembly directory. This change affects the behavior of P/Invokes and the class. ## Version introduced @@ -16,7 +16,7 @@ In .NET 10 Preview 5, specifying `DllImportSearchPath.AssemblyDirectory` as the ## Previous behavior -When `DllImportSearchPath.AssemblyDirectory` 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. +When 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: @@ -29,9 +29,9 @@ In this case, the runtime would search the assembly directory and then fall back ## New behavior -When `DllImportSearchPath.AssemblyDirectory` 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. +When 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 `DllNotFoundException` will be thrown. +The previous code example would now only search the assembly directory for *example.dll*. If the library is not found there, a will be thrown. ## Type of breaking change @@ -39,11 +39,11 @@ This is a [behavioral change](../../categories.md#behavioral-change). ## Reason for change -The fallback behavior when specifying `DllImportSearchPath.AssemblyDirectory` caused confusion and was inconsistent with the design of search flags. This change ensures clarity and consistency in behavior. +The fallback behavior when specifying 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 `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. +If fallback behavior is required, avoid specifying an explicit . 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: @@ -54,6 +54,7 @@ public static extern void ExampleMethod(); ## Affected APIs -- P/Invokes using [`DefaultDllImportSearchPaths`](https://learn.microsoft.com/dotnet/api/system.runtime.interopservices.defaultdllimportsearchpathsattribute) -- [`NativeLibrary.Load`](https://learn.microsoft.com/dotnet/api/system.runtime.interopservices.nativelibrary.load#system-runtime-interopservices-nativelibrary-load(system-string-system-reflection-assembly-system-nullable((system-runtime-interopservices-dllimportsearchpath)))) -- [`NativeLibrary.TryLoad`](https://learn.microsoft.com/dotnet/api/system.runtime.interopservices.nativelibrary.tryload#system-runtime-interopservices-nativelibrary-tryload(system-string-system-reflection-assembly-system-nullable((system-runtime-interopservices-dllimportsearchpath))-system-intptr@)) + +- P/Invokes using +- +- From e5b2f30335e720b50401f8fcd6e5021fcecc1a46 Mon Sep 17 00:00:00 2001 From: Cam Soper Date: Fri, 9 May 2025 18:38:19 -0500 Subject: [PATCH 3/4] fix lint --- .../core/compatibility/interop/10.0/search-assembly-directory.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/core/compatibility/interop/10.0/search-assembly-directory.md b/docs/core/compatibility/interop/10.0/search-assembly-directory.md index b652ff538f24e..7c57a87ae5560 100644 --- a/docs/core/compatibility/interop/10.0/search-assembly-directory.md +++ b/docs/core/compatibility/interop/10.0/search-assembly-directory.md @@ -54,7 +54,6 @@ public static extern void ExampleMethod(); ## Affected APIs - - P/Invokes using - - From 98367fc6887e922bcd4903e5ebb37518c08936a0 Mon Sep 17 00:00:00 2001 From: Cam Soper Date: Fri, 9 May 2025 18:40:20 -0500 Subject: [PATCH 4/4] Update docs/core/compatibility/interop/10.0/search-assembly-directory.md Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> --- .../compatibility/interop/10.0/search-assembly-directory.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/core/compatibility/interop/10.0/search-assembly-directory.md b/docs/core/compatibility/interop/10.0/search-assembly-directory.md index 7c57a87ae5560..27b50dbba4779 100644 --- a/docs/core/compatibility/interop/10.0/search-assembly-directory.md +++ b/docs/core/compatibility/interop/10.0/search-assembly-directory.md @@ -8,7 +8,7 @@ ms.custom: https://github.com/dotnet/docs/issues/45911 # Specifying DllImportSearchPath.AssemblyDirectory only searches the assembly directory -In .NET 10 Preview 5, specifying as the only search flag now restricts the runtime to search exclusively in the assembly directory. This change affects the behavior of P/Invokes and the class. +Starting in .NET 10, if you specify as the only search flag, the runtime searches exclusively in the assembly directory. This change affects the behavior of P/Invokes and the class. ## Version introduced