From 9496e6294ef25fc3ee3cd19f09ed4ca93dd11a9e Mon Sep 17 00:00:00 2001 From: Aaron Robinson Date: Fri, 18 Mar 2022 09:56:51 -0700 Subject: [PATCH 1/3] Add documentation for the PInvoke probe algorithm. --- docs/core/dependency-loading/default-probing.md | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/docs/core/dependency-loading/default-probing.md b/docs/core/dependency-loading/default-probing.md index fa724b4586f89..d9069b107a4a5 100644 --- a/docs/core/dependency-loading/default-probing.md +++ b/docs/core/dependency-loading/default-probing.md @@ -67,4 +67,18 @@ If any matching file exists, attempt to load and return it. ## Unmanaged (native) library probing -When probing to locate an unmanaged library, the `NATIVE_DLL_SEARCH_DIRECTORIES` are searched looking for a matching library. +The runtime's unmanaged library probing algorithm is identical on all platforms. However, since the actual load of the unmanaged library is performed by the underlying platform the observed behavior can be slightly different. + +1) Check if the supplied library name represents an absolute or relative path. + +1) If the name represents an absolute path, use the name directly for all subsequent operations. Otherwise, use the name and create platform defined combinations to consider. Combinations consist of platform specific prefixes (for example, `lib`) and/or suffixes (for example, `.dll`, `.dylib`, `.so`). This is not an exhaustive list nor represents the exact effort made on each platforms, but instead an example of what is considered. + +1) The name and if relative each combination, is then used in the following. The first load attempt to succeed immediately returns the handle to the loaded library. + + - Append to each path supplied in the `NATIVE_DLL_SEARCH_DIRECTORIES` property and attempt to load. + + - If `DllImportSearchPath.AssemblyDirectory` is defined on the calling Assembly, use directly and attempt to load relative to the calling Assembly. + + - Use directly to load the library. + +1) Indicate failure to load the library. From 37839f6638d8dfdd525e4d18a4c4823c86ed81b2 Mon Sep 17 00:00:00 2001 From: Aaron Robinson Date: Fri, 18 Mar 2022 10:11:20 -0700 Subject: [PATCH 2/3] Link to cross-platform P/Invoke guidance. --- docs/core/dependency-loading/default-probing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/core/dependency-loading/default-probing.md b/docs/core/dependency-loading/default-probing.md index d9069b107a4a5..87629bf2af7a4 100644 --- a/docs/core/dependency-loading/default-probing.md +++ b/docs/core/dependency-loading/default-probing.md @@ -67,7 +67,7 @@ If any matching file exists, attempt to load and return it. ## Unmanaged (native) library probing -The runtime's unmanaged library probing algorithm is identical on all platforms. However, since the actual load of the unmanaged library is performed by the underlying platform the observed behavior can be slightly different. +The runtime's unmanaged library probing algorithm is identical on all platforms. However, since the actual load of the unmanaged library is performed by the underlying platform the observed behavior can be slightly different. Guidance on how to author [cross-platform P/Invokes](../../standard/native-interop/cross-platform.md) should be consulted for further details. 1) Check if the supplied library name represents an absolute or relative path. From 06c6dc9ad53aab6f4b9c2aa6bb11ba227b3f8f1c Mon Sep 17 00:00:00 2001 From: Aaron Robinson Date: Fri, 18 Mar 2022 11:40:15 -0700 Subject: [PATCH 3/3] Apply suggestions from code review Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> --- docs/core/dependency-loading/default-probing.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/core/dependency-loading/default-probing.md b/docs/core/dependency-loading/default-probing.md index 87629bf2af7a4..a5acc773089ac 100644 --- a/docs/core/dependency-loading/default-probing.md +++ b/docs/core/dependency-loading/default-probing.md @@ -67,18 +67,18 @@ If any matching file exists, attempt to load and return it. ## Unmanaged (native) library probing -The runtime's unmanaged library probing algorithm is identical on all platforms. However, since the actual load of the unmanaged library is performed by the underlying platform the observed behavior can be slightly different. Guidance on how to author [cross-platform P/Invokes](../../standard/native-interop/cross-platform.md) should be consulted for further details. +The runtime's unmanaged library probing algorithm is identical on all platforms. However, since the actual load of the unmanaged library is performed by the underlying platform, the observed behavior can be slightly different. For more information, see the guidance on how to author [cross-platform P/Invokes](../../standard/native-interop/cross-platform.md). 1) Check if the supplied library name represents an absolute or relative path. -1) If the name represents an absolute path, use the name directly for all subsequent operations. Otherwise, use the name and create platform defined combinations to consider. Combinations consist of platform specific prefixes (for example, `lib`) and/or suffixes (for example, `.dll`, `.dylib`, `.so`). This is not an exhaustive list nor represents the exact effort made on each platforms, but instead an example of what is considered. +1) If the name represents an absolute path, use the name directly for all subsequent operations. Otherwise, use the name and create platform-defined combinations to consider. Combinations consist of platform specific prefixes (for example, `lib`) and/or suffixes (for example, `.dll`, `.dylib`, and `.so`). This is not an exhaustive list, and it doesn't represent the exact effort made on each platform. It's just an example of what is considered. -1) The name and if relative each combination, is then used in the following. The first load attempt to succeed immediately returns the handle to the loaded library. +1) The name and, if the path is relative, each combination, is then used in the following steps. The first successful load attempt immediately returns the handle to the loaded library. - - Append to each path supplied in the `NATIVE_DLL_SEARCH_DIRECTORIES` property and attempt to load. + - Append it to each path supplied in the `NATIVE_DLL_SEARCH_DIRECTORIES` property and attempt to load. - - If `DllImportSearchPath.AssemblyDirectory` is defined on the calling Assembly, use directly and attempt to load relative to the calling Assembly. + - If `DllImportSearchPath.AssemblyDirectory` is defined on the calling assembly, use it directly and attempt to load relative to the calling assembly. - - Use directly to load the library. + - Use it directly to load the library. -1) Indicate failure to load the library. +1) Indicate that the library failed to load.