Carregamento de biblioteca nativa

Este artigo explica quais caminhos o runtime pesquisa ao carregar bibliotecas nativas por meio de P/Invoke. Este exemplo também mostra como usar SetDllImportResolver.

Variações do nome de biblioteca

Para simplificar o código P/Invoke entre plataformas, o runtime adiciona a extensão de biblioteca compartilhada canônica (.dll, .so ou .dylib) a nomes de biblioteca nativa. Em plataformas baseadas em Unix, o runtime também tentará anexar lib. Essas variações de nomes de biblioteca são pesquisadas automaticamente quando você usa APIs que carregam bibliotecas nativas, como DllImportAttribute.

Considere o seguinte exemplo de uso de P/Invoke:

[DllImport("nativedep")]
static extern int ExportedFunction();

Ao executar no Windows, a DLL é pesquisada na seguinte ordem:

1. nativedep
2. nativedep.dll (se o nome da biblioteca já não terminar com .dll ou .exe)

Ao ser executado no Linux ou no macOS, o runtime tentará preceder lib e acrescentar a extensão de biblioteca compartilhada canônica. Nesses sistemas operacionais, as variações do nome de biblioteca são tentadas na seguinte ordem:

1. nativedep.so / nativedep.dylib
2. libnativedep.so / libnativedep.dylib ¹
3. nativedep
4. libnativedep ¹

No Linux, a ordem de pesquisa será diferente se o nome da biblioteca terminar com .so ou contiver .so. (observe o . à direita). Considere o seguinte exemplo:

[DllImport("nativedep.so.6")]
static extern int ExportedFunction();

Nesse caso, as variações do nome de biblioteca são tentadas na seguinte ordem:

1. nativedep.so.6
2. libnativedep.so.6 ¹
3. nativedep.so.6.so
4. libnativedep.so.6.so ¹

¹ O caminho será verificado somente se o nome da biblioteca não contiver um caractere separador de diretório (/).

Resolvedor de importação personalizado

Em cenários mais complexos, você pode usar SetDllImportResolver para resolver as importações de DLL em tempo de execução. No exemplo a seguir, nativedep será resolvido como nativedep_avx2 se a CPU der suporte.

using System;
using System.Reflection;
using System.Runtime.InteropServices;

namespace PInvokeSamples
{
    public static partial class Program
    {
        [LibraryImport("nativedep")]
        private static partial int ExportedFunction();

        public static void Main(string[] args)
        {
            // Register the import resolver before calling the imported function.
            // Only one import resolver can be set for a given assembly.
            NativeLibrary.SetDllImportResolver(Assembly.GetExecutingAssembly(), DllImportResolver);

            int value = ExportedFunction();
            Console.WriteLine(value);
        }

        private static IntPtr DllImportResolver(string libraryName, Assembly assembly, DllImportSearchPath? searchPath)
        {
            if (libraryName == "nativedep")
            {
                // On systems with AVX2 support, load a different library.
                if (System.Runtime.Intrinsics.X86.Avx2.IsSupported)
                {
                    return NativeLibrary.Load("nativedep_avx2", assembly, searchPath);
                }
            }

            // Otherwise, fallback to default import resolver.
            return IntPtr.Zero;
        }
    }
}

Confira também

• Invocação de plataforma (P/Invoke)