Class NativeLibraryHelper

Namespace

Stride.Core

Assembly

Stride.Core.dll

Provides helper methods for locating, preloading, registering, and unloading native libraries and executables across different platforms.

public static class NativeLibraryHelper

Inheritance

object

NativeLibraryHelper

Remarks

NativeLibraryHelper is designed to support scenarios where managed assemblies depend on platform-specific native binaries, such as when distributing .NET assemblies with associated CPU-architecture-specific libraries. It abstracts the complexity of locating and loading these native libraries from various runtime and environment-specific locations, and ensures that libraries are loaded and unloaded in a thread-safe manner.

Methods in this class are particularly useful for applications that need to dynamically resolve and manage native dependencies at runtime, such as plugins or cross-platform frameworks.

Methods

LocateExecutable(string, Type)

Locates the full path to a native executable file by searching known locations and runtime-specific directories.

public static string LocateExecutable(string executableName, Type ownerType)

Parameters

executableName string

The name of the executable file to locate, including the extension.

ownerType Type

The type whose assembly is used to determine runtime-specific search paths for the executable.

Returns

string

The full path to the located executable file.

Remarks

This method is typically used to resolve platform-specific native binaries required by managed code.

Exceptions

FileNotFoundException

Thrown if the executable file cannot be found in any of the searched locations.

LocateLibrary(string, Type)

Locates the full path to a native library, appending the current platform's library extension (.dll, .so, .dylib) to libraryName before searching. On Linux/macOS, SONAME-versioned variants (for example, libfoo.so.6 or libfoo.6.dylib) are matched and the highest version is returned; the lib prefix is also tried when omitted, matching the conventions PreloadLibrary(string, Type) uses.

public static string LocateLibrary(string libraryName, Type ownerType)

Parameters

libraryName string

The library name without extension (for example, "libassimp" or "assimp").

ownerType Type

The type whose assembly is used to determine runtime-specific search paths for the library.

Returns

string

The full path to the located native library.

Exceptions

FileNotFoundException

Thrown if the library cannot be found in any of the searched locations.

PreloadLibrary(string, Type)

Preloads a native library (or returns the handle of one already loaded), so subsequent P/Invoke calls use it instead of triggering their own load. The returned OS module handle also lets callers that resolve exports themselves (for example, libraries with their own function-pointer binding) share the engine's native resolution.

public static nint PreloadLibrary(string libraryName, Type ownerType)

Parameters

libraryName string

The name of the library, without the extension.

ownerType Type

The Type whose Assembly location is related to the native library. This is needed because GetCallingAssembly() cannot be used, as it might be wrong due to optimizations.

Returns

nint

The OS module handle of the loaded library.

Remarks

Preloading native libraries can be useful when we want to have a .NET assembly for the AnyCPU platform, and an associated CPU-specific native library.

By preloading the native library, we ensure that it is loaded before any P/Invoke calls, so those calls use the already loaded library instead of trying to load it again.

Exceptions

DllNotFoundException

The library with name libraryName could not be loaded.

RegisterDependency(string)

Registers a native library as a dependency.

public static void RegisterDependency(string libraryPath)

Parameters

libraryPath string

The full path to the native library.

Exceptions

ArgumentNullException

libraryPath is null.

Unload(string)

Unloads a native library that was loaded previously by PreloadLibrary(string, Type).

public static void Unload(string libraryName)

Parameters

libraryName string

The name of the library to unload.

UnloadAll()

Unloads all native libraries that were loaded previously by PreloadLibrary(string, Type).

public static void UnloadAll()