Integracja natywnego kodu w .NET: P/Invoke, DllImport, wieloplatformowość

Integracja natywnego kodu w .NET: praktyczny przewodnik dla programistów

Użycie natywnego kodu w aplikacjach .NET pozwala rozszerzać funkcjonalność poza standardową bibliotekę. To podejście jest szczególnie istotne przy pracy z niskopoziomowymi API systemów operacyjnych lub interfejsami sprzętowymi, takimi jak MIDI. W artykule omawiamy kluczowe aspekty integracji: od podstawowego użycia DllImport po tworzenie rozwiązań wieloplatformowych i pakowanie w pakiety NuGet.

Podstawy P/Invoke i DllImport

Mechanizm P/Invoke (Platform Invoke) zapewnia wywołanie natywnych funkcji z zarządzanego kodu .NET. Podstawowy przykład użycia atrybutu DllImport do pracy z Windows API:

[DllImport("winmm.dll")]
static extern uint midiInGetNumDevs();

Kluczowe cechy DllImport:

• Określenie nazwy biblioteki i punktu wejścia (EntryPoint)
• Automatyczne marshaling typów danych
• Obsługa różnych konwencji wywołań

Marshaling — proces przekształcania typów danych między pamięcią zarządzaną a niezarządzaną. To obejmuje:

• Przekształcanie typów prymitywnych (int, float)
• Pracę z ciągami znaków (string na LPWSTR)
• Zarządzanie strukturami i wskaźnikami
• Alokację i zwalnianie niezarządzanej pamięci

Rozwiązania wieloplatformowe

Przy opracowywaniu dla wielu systemów operacyjnych pojawiają się specyficzne wymagania:

• Różne biblioteki systemowe:

- Windows: winmm.dll

- macOS: CoreMIDI.framework

- Linux: ALSA przez libasound

• Różne funkcje API:

- Windows: midiInGetNumDevs()

- macOS: MIDIGetNumberOfSources()

- Linux: funkcje snd_seq_*

• Różne ścieżki do bibliotek:

- Windows: prosta nazwa DLL

- macOS: pełna ścieżka do frameworku

Aby określić system operacyjny, użyj RuntimeInformation:

if (RuntimeInformation.IsOSPlatform(OSPlatform.Windows))
    count = midiInGetNumDevs();
else if (RuntimeInformation.IsOSPlatform(OSPlatform.OSX))
    count = MIDIGetNumberOfSources();

Tworzenie natywnego backendu

Zunifikowane podejście zakłada stworzenie własnej natywnej warstwy, która ukrywa różnice między platformami.

Struktura projektu:

• Native-Windows.cpp → Native.dll
• Native-macOS.cpp → Native.dylib
• Native-Linux.cpp → Native.so

Przykład implementacji dla Windows:

extern "C" __declspec(dllexport) int GetInputDevicesCount()
{
    return midiInGetNumDevs();
}

Przykład implementacji dla macOS:

extern "C" int GetInputDevicesCount()
{
    return MIDIGetNumberOfSources();
}

Zalety podejścia:

• Jednolite API dla wszystkich platform
• Izolacja kodu specyficznego dla platformy
• Uproszczenie kodu C#
• Możliwość dodania dodatkowej logiki

Kompilacja i zarządzanie binariami

Proces kompilacji natywnych bibliotek zależy od docelowej platformy:

Dla Windows (MSVC):

cl /LD Native-Windows.cpp /link /OUT:Native.dll

Dla macOS (Clang):

clang++ -dynamiclib -o Native.dylib Native-macOS.cpp -framework CoreMIDI

Dla Linux (GCC):

g++ -shared -fPIC -o Native.so Native-Linux.cpp -lasound

Lokalizacja plików w projekcie:

project/
├── src/
│   ├── Native/
│   │   ├── Windows/
│   │   │   ├── x64/
│   │   │   │   └── Native.dll
│   │   │   └── arm64/
│   │   │       └── Native.dll
│   │   ├── macOS/
│   │   │   ├── x64/
│   │   │   │   └── Native.dylib
│   │   │   └── arm64/
│   │   │       └── Native.dylib
│   │   └── Linux/
│   │       └── x64/
│   │           └── Native.so
│   └── Managed/
│       └── MidiWrapper.cs
└── MidiWrapper.csproj

Nowoczesne podejścia do P/Invoke

Atrybut LibraryImport

W .NET 7+ pojawił się nowy atrybut LibraryImport, który generuje kod marshalingu podczas kompilacji:

[LibraryImport("Native")]
internal static partial int GetInputDevicesCount();

Zalety LibraryImport:

• Generacja kodu podczas kompilacji
• Poprawiona wydajność
• Surowsza weryfikacja typów
• Obsługa generatorów źródłowych

Bezpieczne zarządzanie zasobami

IntPtr vs SafeHandle:

• IntPtr — prosty wskaźnik, wymaga ręcznego zarządzania
• SafeHandle — bezpieczna otoczka z automatycznym zwalnianiem

Przykład użycia SafeHandle:

sealed class MidiHandle : SafeHandle
{
    public MidiHandle() : base(IntPtr.Zero, true) { }
    
    public override bool IsInvalid => handle == IntPtr.Zero;
    
    protected override bool ReleaseHandle()
    {
        return midiInClose(handle) == 0;
    }
}

Praca z callbackami i asynchronicznością

Specyfika wywołań z callbacków:

• Niektóre natywne funkcje nie mogą być wywoływane z callbacków
• Wymagana synchronizacja między wątkami
• Możliwe deadlock'i przy nieprawidłowym użyciu

Wzorzec do pracy z buforami w MIDI:

• Inicjalizacja wielu buforów z góry
• W callbacku — ponowne użycie bufora z danymi
• Unikanie wywołań unprepared/close w callbackach
• Używanie struktur danych bezpiecznych dla wątków

Przykład bezpiecznego callbacku:

private static void MidiCallback(IntPtr handle, uint msg, IntPtr instance, IntPtr param1, IntPtr param2)
{
    // Wyodrębnianie danych z bufora
    var data = ExtractMidiData(param1);
    
    // Asynchroniczne przetwarzanie
    Task.Run(() => ProcessMidiDataAsync(data));
    
    // Ponowne dodanie bufora
    lock (bufferLock)
    {
        midiInAddBuffer(handle, param1, Marshal.SizeOf<MIDIHDR>());
    }
}

Pakowanie w pakiet NuGet

Struktura pakietu NuGet z natywnymi bibliotekami:

<PackageReference>
  <NativeLibs>
    <RuntimeIdentifier>win-x64</RuntimeIdentifier>
    <NativeLib>runtimes/win-x64/native/Native.dll</NativeLib>
  </NativeLibs>
  <NativeLibs>
    <RuntimeIdentifier>osx-arm64</RuntimeIdentifier>
    <NativeLib>runtimes/osx-arm64/native/Native.dylib</NativeLib>
  </NativeLibs>
</PackageReference>

Kluczowe dyrektywy w .csproj:

<ItemGroup>
  <Content Include="runtimes\win-x64\native\Native.dll">
    <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
    <PackagePath>runtimes/win-x64/native/</PackagePath>
  </Content>
  <Content Include="runtimes\osx-arm64\native\Native.dylib">
    <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
    <PackagePath>runtimes/osx-arm64/native/</PackagePath>
  </Content>
</ItemGroup>

Co ważne:

• Prawidłowa organizacja plików według RID (Runtime Identifier)
• Określenie docelowych platform w .csproj
• Testowanie instalacji pakietu na różnych systemach
• Obsługa architektur x64 i ARM64

Optymalizacja wydajności

Metody redukcji narzutów:

• Minimalizacja przejść między kodem zarządzanym a niezarządzanym
• Używanie typów blittable (nie wymagających marshalingu)
• Buforowanie deskryptorów i wskaźników
• Przetwarzanie zbiorcze wywołań

Typy blittable:

• byte, sbyte, short, ushort, int, uint, long, ulong
• float, double
• struktury zawierające tylko typy blittable

Przykład zoptymalizowanej struktury:

[StructLayout(LayoutKind.Sequential)]
struct MidiMessage
{
    public uint Timestamp;
    public byte Status;
    public byte Data1;
    public byte Data2;
    public byte Reserved;
}

Debugowanie i diagnostyka

Narzędzia do debugowania natywnego kodu:

• WinDbg i CDB dla Windows
• LLDB dla macOS i Linux
• Visual Studio Mixed Mode Debugging
• JetBrains Rider z obsługą debugowania natywnego

Typowe problemy i rozwiązania:

• Access Violation: nieprawidłowe marshaling typów
• Memory Leaks: niezwolnione zasoby
• Deadlocks: blokady w callbackach
• Performance Issues: częste wywołania P/Invoke

Logowanie wywołań:

[DllImport("Native", EntryPoint = "GetInputDevicesCount")]
private static extern int NativeGetInputDevicesCount();

public static int GetInputDevicesCount()
{
    Logger.Debug($"Calling native GetInputDevicesCount");
    var result = NativeGetInputDevicesCount();
    Logger.Debug($"Native function returned: {result}");
    return result;
}

Przyszłość integracji natywnej w .NET

Trendy i kierunki rozwoju:

• Source Generators: automatyczna generacja kodu P/Invoke
• NativeAOT: kompilacja do natywnego kodu bez runtime'u
• WASI: uruchamianie .NET w WebAssembly z dostępem do systemowych API
• Bardziej ścisła integracja z językami jak Rust i C++

Przykład użycia Source Generators:

[NativeMethod("Native", "GetInputDevicesCount")]
public static partial int GetInputDevicesCount();

Co ważne

• P/Invoke pozostaje głównym mechanizmem do wywoływania natywnego kodu
• Wieloplatformowość wymaga tworzenia zunifikowanego API
• Prawidłowe zarządzanie zasobami jest kluczowe dla stabilności
• Pakiety NuGet powinny zawierać binaria dla wszystkich docelowych platform
• Nowoczesne podejścia (LibraryImport, Source Generators) upraszczają rozwój

— Editorial Team