dotnet-pinvoke

What it does

Guides building and reviewing native interop between .NET and C/C++ libraries using DllImport and LibraryImport. It covers choosing between DllImport and LibraryImport, mapping native types to .NET types, writing declarations (including EntryPoint and calling conventions), correct string encoding, memory ownership models, and using SafeHandle for native handles. It also includes error handling, callbacks, and cross-platform library loading and resolving, with guidance for migrating code to LibraryImport for .NET 7+ and AOT/trimming considerations.

How it works

• Step 1: Choose DllImport or LibraryImport based on target framework and AOT needs; LibraryImport is preferred for .NET 7+ and AOT/trimming safety.
• Step 2: Map native types (e.g., long, size_t, BOOL, HANDLE, LPWSTR/LPSTR) to .NET types with cautions (e.g., use CLong, nuint/UIntPtr, SafeHandle, string encodings).
• Step 3: Write the declaration using DllImport or LibraryImport, include EntryPoint when names differ, and add appropriate CallingConvention only when targeting Windows x86.
• Step 4: Handle strings by explicitly selecting encodings (UTF-16 on Windows, UTF-8 for cross-platform C libraries); avoid CharSet.Auto and incorrect marshalling.
• Step 5: Establish memory ownership rules and choose model for who allocates/frees memory; avoid mismatched allocators.
• Step 6: Use SafeHandle for native handles to avoid leaks and double-frees; implement ReleaseHandle.
• Step 7: Handle errors via SetLastError, HRESULTs, and converting to exceptions as appropriate.
• Step 8: Handle callbacks with UnmanagedCallersOnly in .NET 8+, or rooted delegates when necessary; ensure lifetime and GC rooting to prevent crashes.
• Cross-Platform Library Loading: use NativeLibrary.SetDllImportResolver or platform-specific naming, with guidance on simple vs complex scenarios.
• Migrating DllImport to LibraryImport: steps to convert existing DllImport code to LibraryImport for .NET 7+ with partial classes and updated attributes.

When to use it

Use this skill when you are:

• Writing new [DllImport] or [LibraryImport] declarations from C/C++ headers
• Reviewing P/Invoke signatures for correctness (types, calling conventions, string encoding)
• Wrapping a C library for .NET
• Debugging boundary issues such as AccessViolationException or memory corruption
• Migrating DllImport declarations to LibraryImport for AOT/trimming compatibility
• Diagnosing memory leaks or heap corruption involving native handles or buffers

What it can touch

• Declarations using [DllImport] and [LibraryImport]
• Type mappings between C/Win32 types and .NET types (e.g., CLong, nuint, SafeHandle, string encodings)
• Error handling constructs and exceptions related to P/Invoke
• SafeHandle implementations and their ReleaseHandle logic
• Memory ownership examples and allocation/free patterns
• Callback mechanisms and function pointer handling
• NativeLibrary resolution and runtime platform checks for loading

Caveats

• Do not use for COM interop or C++/CLI mixed-mode assemblies, or code with no native dependencies
• Use LibraryImport only on .NET 7+; DllImport remains for .NET Framework
• Ensure explicit string encoding; avoid CharSet.Auto and unsafe defaults
• Be cautious with memory ownership and allocator compatibility; mismatched frees cause heap corruption
• Callbacks require careful lifetime management; delegates must be rooted if native code stores function pointers
• The guidance emphasizes avoiding risky patterns unless explicitly required by the native API or target platform