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.

PreloadLibrary(string, Type)

Try to preload a native library.

public static void 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.

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()