Platform Invoke (P/Invoke)#

Platform Invoke (P/Invoke) to mechanizm pozwalający kodowi zarządzanemu (C#) na wywoływanie funkcji niezarządzanych zaimplementowanych w bibliotekach dynamicznych DLL (biblioteki współdzielone w systemach Unix), np. API systemu Windows (WinAPI) lub własne biblioteki napisane w C/C++.

Atrybut DllImport#

Przykładowo, jeśli chcemy wywołać funkcję z user32.dll z WinAPI:

int MessageBox(HWND hWnd, LPCTSTR lpText, LPCTSTR lpCaption, UINT uType);

Tradycyjnym sposobem deklarowania funkcji zewnętrznych jest użycie atrybutu [DllImport]. Metoda musi być zadeklarowana jako static i extern.

using System.Runtime.InteropServices;

public class NativeMethods
{
    [DllImport("user32.dll")]
    public static extern int MessageBox(nint hWnd, string text, string caption, uint type);
}

Wywołanie:

NativeMethods.MessageBox(nint.Zero, "Hello world!", "Info", 0);

Na systemach z rodziny Unix możesz spróbować wywołać np. getpid z libc:

[DllImport("libc")]
public static extern int getpid();

Atrybut LibraryImport (.NET 7+)#

Od wersji .NET 7 wprowadzono atrybut [LibraryImport], który wykorzystuje generatory kodu źródłowego (Source Generators) zamiast generowania kodu w czasie wykonywania (jak DllImport). Jest to bardziej wydajne rozwiązanie. W nowych projektach zaleca się stosowanie LibraryImport zamiast DllImport.

Metoda musi być statyczna i oznaczona jako partial, aby generator mógł dopisać implementację (typ, w którym się znajduje, również musi być partial). Wygenerowany kod używa wskaźników, więc w projekcie trzeba też włączyć AllowUnsafeBlocks (w przeciwnym razie kompilacja kończy się błędem SYSLIB1062).

W przeciwieństwie do DllImport, LibraryImport nie zakłada żadnego domyślnego sposobu marshallingu dla typów string i bool - trzeba go podać jawnie (np. przez StringMarshalling lub [MarshalAs]), w przeciwnym razie kompilacja kończy się błędem SYSLIB1051. Nie wyszukuje też wariantów nazw funkcji WinAPI z przyrostkiem A/W, dlatego trzeba podać dokładną nazwę MessageBoxW (wersja UTF-16).

public partial class NativeMethods
{
    [LibraryImport("user32.dll", EntryPoint = "MessageBoxW", StringMarshalling = StringMarshalling.Utf16)]
    public static partial int MessageBox(nint hWnd, string text, string caption, uint type);
}

Wywołanie własnej biblioteki C++#

Najważniejsze jest użycie extern "C". Kompilatory C++ domyślnie zmieniają nazwy funkcji (tzw. Name Mangling), dodając do nich informacje o argumentach czy przestrzeniach nazw. extern "C" wyłącza to zachowanie, dzięki czemu C# może znaleźć taką funkcję. Makro EXPORT sprawia, że funkcja staje się widoczna na zewnątrz biblioteki.

#if defined(_WIN32) || defined(_WIN64)
#define EXPORT __declspec(dllexport)
#else
#define EXPORT __attribute__((visibility("default")))
#endif

extern "C" EXPORT void Hello();

Następnie po stronie C# musimy zaimportować tę funkcję, używając atrybutu DllImport lub LibraryImport.

[LibraryImport("HelloCpp")]
private static partial void Hello();

Przykład:
C++

C#

Wyszukiwanie bibliotek i NativeLibrary#

Nazwę biblioteki podaje się bez przedrostka i rozszerzenia. Środowisko uruchomieniowe dodaje rozszerzenie właściwe dla platformy (.dll, .so, .dylib), a na systemach Unix próbuje też przedrostka lib, więc "HelloCpp" odnajduje HelloCpp.dll na Windowsie, libHelloCpp.so na Linuksie i libHelloCpp.dylib na macOS. Domyślnie biblioteka jest szukana w katalogu aplikacji (katalogu assembly) oraz w standardowych lokalizacjach systemowych.

Bibliotekę można też załadować ręcznie za pomocą klasy NativeLibrary (.NET Core 3.0), która jest odpowiednikiem dlopen/dlsym (LoadLibrary/GetProcAddress na Windowsie). Adres wyeksportowanej funkcji można następnie wywołać przez niezarządzany wskaźnik na funkcję (zob. Kontekst niebezpieczny):

unsafe
{
    nint library = NativeLibrary.Load("HelloCpp", typeof(Program).Assembly, null);
    try
    {
        var hello = (delegate* unmanaged<void>)NativeLibrary.GetExport(library, "Hello");
        hello(); // Hello from C++
    }
    finally
    {
        NativeLibrary.Free(library);
    }
}

Metoda NativeLibrary.SetDllImportResolver pozwala zastąpić sposób wyszukiwania bibliotek używanych przez deklaracje DllImport/LibraryImport danego assembly, np. aby wybrać plik biblioteki w zależności od platformy.

Marshalling#

Marshalling to proces konwersji typów danych między kodem zarządzanym a niezarządzanym.

Typy przekładalne (blittable) i nieprzekładalne (non-blittable)#

  • Typy przekładalne (blittable): Typy, które mają taką samą reprezentację w pamięci w kodzie zarządzanym i niezarządzanym (np. byte, int, float, nint, jednowymiarowe tablice typów przekładalnych, typy bezpośrednie składające się z typów przekładalnych). Nie wymagają dodatkowej konwersji.
  • Typy nieprzekładalne (non-blittable): Typy wymagające konwersji (np. bool, char, string).

Przykładowo, bool nie ma jednej natywnej reprezentacji: w C++ zajmuje 1 bajt, a typ Win32 BOOL (domyślny dla DllImport) to 4-bajtowy int. Stąd atrybut [MarshalAs(UnmanagedType.U1)] poniżej:

extern "C" EXPORT int Foo(unsigned char c, float x, Bar* bar, bool b);
[LibraryImport("HelloCpp")]
public static partial int Foo(byte c, float x, nint bar, [MarshalAs(UnmanagedType.U1)]bool b);

Marshalling napisów#

Napisy w C# (Unicode UTF-16) muszą zostać przekonwertowane z/do formatu oczekiwanego przez funkcję natywną (np. UTF-8, UTF-16).

Jako parametr wejściowy#

Jeżeli napis przekazywany jest jako parametr i nie będzie modyfikowany po stronie natywnego kodu, to wystarczy po stronie C# przekazać go jako string.

extern "C" EXPORT void PrintAnsiString(const char* str);
extern "C" EXPORT void PrintUnicodeString(const char16_t* str);

void PrintAnsiString(const char *str)
{
    std::println("String: '{}'\n", str);
}

void PrintUnicodeString(const char16_t *str)
{
    std::u16string u16string(str);

    std::wstring_convert<std::codecvt_utf8_utf16<char16_t>, char16_t> converter;
    std::string utf8String = converter.to_bytes(u16string);

    std::println("UTF-16 String: '{}'\n", utf8String);
}

A w atrybucie LibraryImport wyspecyfikować, jak napis ma zostać przetworzony przed przekazaniem do funkcji C++.

[LibraryImport("StringsCpp", StringMarshalling = StringMarshalling.Utf8)]
public static partial void PrintAnsiString(string str);

[LibraryImport("StringsCpp", StringMarshalling = StringMarshalling.Utf16)]
public static partial void PrintUnicodeString(string str);

Jako wartość zwracana#

extern "C" EXPORT const char* GetAnsiString();
extern "C" EXPORT const char16_t* GetUnicodeString();

const char *GetAnsiString()
{
    static const char *ansiString = "String from C++";
    return ansiString;
}

const char16_t *GetUnicodeString()
{
    static const char16_t *unicodeString = u"UTF-16 string from C++ \U0001F44B";
    return unicodeString;
}

Wartość zwracaną najprościej przechwycić po stronie C# jako wskaźnik. Wszelkie uchwyty do pamięci reprezentujemy po stronie C# jako IntPtr lub od C# 9 jako nint (od C# 11 po prostu alias do System.IntPtr). Jest to typ reprezentujący wskaźnik o rozmiarze zależnym od architektury procesora.

[LibraryImport("StringsCpp")]
public static partial nint GetAnsiString();

[LibraryImport("StringsCpp")]
public static partial nint GetUnicodeString();

Następnie, żeby z takiego wskaźnika odzyskać napis, możemy użyć metod pomocniczych Marshal.PtrToStringAnsi, Marshal.PtrToStringUTF8 lub Marshal.PtrToStringUni.

string? ansi = Marshal.PtrToStringAnsi(GetAnsiString());
string? unicode = Marshal.PtrToStringUni(GetUnicodeString());
Console.WriteLine($"Ansi string: {ansi}");
Console.WriteLine($"Unicode string: {unicode}");

Typ zwracany można by też zadeklarować jako string, ale wtedy marshaller przejmuje na własność zwrócony bufor i po konwersji go zwalnia (funkcją CoTaskMemFree na Windowsie, free na Uniksie). Tutaj oznaczałoby to zwolnienie statycznego literału napisowego, co kończy się awarią procesu (free(): invalid pointer). Zwracając nint, zarządzanie pamięcią pozostawiamy sobie.

Jako parametr wejściowo-wyjściowy#

Jeżeli funkcja C++ modyfikuje przekazany jako parametr napis, to nie możemy po stronie C# przekazać obiektu string - jest niezmienny.

extern "C" EXPORT void Encode(char* text);

void Encode(char *text)
{
    if (text == nullptr) return;

    while (*text)
    {
        char c = *text;

        if (c >= 'A' && c <= 'Z')
        {
            *text = static_cast<char>(((c - 'A' + 13) % 26) + 'A');
        }
        else if (c >= 'a' && c <= 'z')
        {
            *text = static_cast<char>(((c - 'a' + 13) % 26) + 'a');
        }

        text++;
    }
}

Najprościej jest wtedy przekazać tablicę znaków (byte[] lub char[] w zależności od kodowania). W poniższym przykładzie zakładamy kodowanie UTF-8 (kompatybilne z ASCII). Funkcja natywna oczekuje napisu zakończonego znakiem zerowym, więc tablica musi kończyć się '\0' - ToArray() na literale u8 nie kopiuje terminatora.

[LibraryImport("StringsCpp")]
public static partial void Encode([In, Out] byte[] str);
byte[] arr = "Initial content\0"u8.ToArray();
Encode(arr);
Console.WriteLine($"Encoded: {Encoding.UTF8.GetString(arr, 0, arr.Length - 1)}"); // Encoded: Vavgvny pbagrag

Przykład:
C++

C#

Marshalling struktur#

struct Color
{
    union
    {
        struct
        {
            uint8_t r;
            uint8_t g;
            uint8_t b;
            uint8_t a;
        };

        uint32_t rgba;
    };
};

Aby przekazać strukturę z/do kodu natywnego, należy zdefiniować jej odpowiednik w C# i, jeżeli to konieczne, użyć atrybutu [StructLayout]. Atrybut ten ma jeden parametr pozycyjny LayoutKind, który może przyjmować jedną z trzech wartości:

  • Sequential: Pola są ułożone w pamięci w kolejności deklaracji (zachowanie domyślne dla struct).
  • Explicit: Pozwala ręcznie określić przesunięcie każdego pola za pomocą atrybutu [FieldOffset]. Używane do tworzenia odpowiedników unii.
  • Auto: Układ wybiera środowisko uruchomieniowe (zachowanie domyślne dla class). Takich typów nie można przekazywać do kodu natywnego.

Opcjonalny parametr Pack pozwala również wyspecyfikować wyrównanie pól (alignment).

[StructLayout(LayoutKind.Explicit)]
public struct Color
{
    [FieldOffset(0)]
    public byte R;
    [FieldOffset(1)]
    public byte G;
    [FieldOffset(2)]
    public byte B;
    [FieldOffset(3)]
    public byte A;
    [FieldOffset(0)]
    public uint Rgba;
}

Przekazanie struktur#

extern "C" EXPORT Color Add(Color a, Color b);
extern "C" EXPORT void Darken(Color *color);
extern "C" EXPORT void PrintHex(Color color);
[LibraryImport("StructsCpp")]
private static partial Color Add(Color a, Color b);

[LibraryImport("StructsCpp")]
private static partial void Darken(ref Color b);

[LibraryImport("StructsCpp")]
private static partial void PrintHex(Color a);

Przykład:
C++

C#

Przekazywanie funkcji#

Możemy przekazywać metody C# do kodu niezarządzanego jako wskaźniki na funkcje lub delegaty.

typedef void (*Callback)(int value);

extern "C" EXPORT void Count(int from, int to, Callback callback);

void Count(int from, int to, Callback callback)
{
    for (int i = from; i < to; ++i) {
        callback(i);
    }
}
public delegate void Callback(int value);
    
[LibraryImport("CallbacksCpp")]
private static partial void Count(int from, int to, Callback callback);

[LibraryImport("CallbacksCpp")]
private static unsafe partial void Count(int from, int to, delegate* unmanaged<int, void> callback);

Delegat (np. lambdę) marshaller zamienia na natywny wskaźnik na funkcję. Wskaźnik na funkcję przekazywany do kodu natywnego musi być zadeklarowany jako unmanaged - zwykły delegate* używa zarządzanej konwencji wywołania, z której kod natywny nie może skorzystać. Można do niego przypisać wyłącznie adres statycznej metody oznaczonej atrybutem [UnmanagedCallersOnly]. Takiej metody nie można wywołać bezpośrednio z C#, a wyjątki nie mogą się z niej wydostać.

static unsafe void Main()
{
    Count(1, 101, i => Console.WriteLine(i));
    Count(1, 101, &FizzBuzz);
}

[UnmanagedCallersOnly]
static void FizzBuzz(int i)
{
    // ...
}

Garbage Collector nie widzi referencji trzymanej przez kod niezarządzany. Jeśli przekażesz delegat do funkcji natywnej, która użyje go później (asynchronicznie), musisz zadbać o to, by delegat nie został usunięty przez GC (np. przypisując go do statycznego pola). Wskaźnik na statyczną metodę [UnmanagedCallersOnly] nie ma tego problemu.

Przykład:
C++

C#

SafeHandle#

Klasa SafeHandle służy do owijania uchwytów do zasobów systemu operacyjnego (pamięć, pliki, gniazda sieciowe, zewnętrzna baza danych) i gwarantuje zwolnienie zasobu nawet w przypadku wystąpienia wyjątku. SafeHandle implementuje IDisposable, ale potrafi też sama zwolnić zasoby w finalizatorze.

extern "C" EXPORT const char* CreateString();
extern "C" EXPORT void PrintString(const char* str);
extern "C" EXPORT void DestroyString(const char* str);

const char *CreateString()
{
    std::println("Creating a C string");
    const char str[] = "C string";
    size_t length = std::strlen(str);
    char* dup = new char[length + 1];
    std::strcpy(dup, str);
    return dup;
}

void PrintString(const char *str)
{
    std::println("The C string is: '{}'", str);
}

void DestroyString(const char *str)
{
    std::println("Destroying a C string");
    delete[] str;
}

Zamiast używać IntPtr/nint dla uchwytów, lepiej jest stworzyć klasy dziedziczące po SafeHandle, które automatycznie będą zarządzać cyklem życia zewnętrznych obiektów.

public class StringSafeHandle : SafeHandle
{
    public StringSafeHandle() : base(nint.Zero, true) {}

    protected override bool ReleaseHandle()
    {
        NativeString.DestroyString(handle);
        handle = nint.Zero;
        return true;
    }

    public override bool IsInvalid => handle == nint.Zero;
}

Użycie w sygnaturze metody:

public static partial class NativeString
{
    [LibraryImport("SafeHandleCpp")]
    public static partial StringSafeHandle CreateString();

    [LibraryImport("SafeHandleCpp")]
    public static partial void PrintString(StringSafeHandle str);

    [LibraryImport("SafeHandleCpp")]
    public static partial void DestroyString(nint str);
}

Przykład:
C++

C#

Obsługa błędów (SetLastError)#

Funkcje natywne często zgłaszają błędy przez kod błędu przechowywany osobno dla każdego wątku: errno na Uniksie lub GetLastError() na Windowsie. Samo środowisko uruchomieniowe może między wywołaniem funkcji natywnej a naszym kodem wywołać funkcje systemowe i nadpisać tę wartość. Dlatego przy SetLastError = true kod marshallingu zapamiętuje kod błędu zaraz po wywołaniu, a my odczytujemy go metodą Marshal.GetLastPInvokeError() (.NET 6; starsza Marshal.GetLastWin32Error() mimo swojej nazwy robi to samo). Marshal.GetPInvokeErrorMessage (.NET 7) zwraca odpowiadający mu komunikat systemowy.

using System.Runtime.InteropServices;

if (Libc.chdir("/nonexistent") != 0)
{
    int error = Marshal.GetLastPInvokeError();
    Console.WriteLine($"Error {error}: {Marshal.GetPInvokeErrorMessage(error)}");
    // Error 2: No such file or directory
}

public static partial class Libc
{
    [LibraryImport("libc", StringMarshalling = StringMarshalling.Utf8, SetLastError = true)]
    public static partial int chdir(string path);
}