P/Invoke Fundamentals
Declare and call native functions using DllImport, understand marshaling primitives, strings, and structs.
P/Invoke Fundamentals is a free C# Academy lesson on CoddyKit — lesson 1 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the C# Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.
What Is P/Invoke?
Platform Invocation Services (P/Invoke) lets C# call functions in native shared libraries (.dll on Windows, .so on Linux, .dylib on macOS). It is the standard mechanism for calling Win32 APIs or any C-ABI library from .NET.
Your First P/Invoke Call
Declare the native function with [DllImport] and give the library name. The CLR handles finding and loading the library and marshalling arguments.
using System.Runtime.InteropServices;
// Calling MessageBoxW from user32.dll (Windows)
internal static partial class NativeMethods
{
[DllImport("user32.dll",
EntryPoint = "MessageBoxW",
CharSet = CharSet.Unicode,
SetLastError = true)]
internal static extern int MessageBox(
IntPtr hwnd,
string text,
string caption,
uint type);
}
// Call it:
NativeMethods.MessageBox(IntPtr.Zero, "Hello!", "P/Invoke", 0);
// Windows-only — wrap in RuntimeInformation.IsOSPlatform check
// for cross-platform codeCalling Custom Native Libraries
P/Invoke works with any C-exported function, not just OS APIs. Build a native library, export functions with C linkage, and call them from C#.
// mymath.h / mymath.c:
// extern "C" double AddNumbers(double a, double b) { return a + b; }
// Compile: gcc -shared -o libmymath.so mymath.c
// C# declaration:
[DllImport("mymath", // libmymath.so / mymath.dll
EntryPoint = "AddNumbers",
CallingConvention = CallingConvention.Cdecl)]
private static extern double AddNumbers(double a, double b);
// Call:
double result = AddNumbers(3.14, 2.72); // 5.86
// .NET resolves the library via:
// 1. Absolute path if provided
// 2. App directory
// 3. OS library path (PATH / LD_LIBRARY_PATH / DYLD_LIBRARY_PATH)Marshalling Basic Types
The CLR automatically marshals most primitive types between managed and native representations. Knowing the mappings avoids subtle bugs.
// C Type → C# Type
// int (32-bit) → int or System.Int32
// long (64-bit) → long or System.Int64
// float → float
// double → double
// bool → [MarshalAs(UnmanagedType.Bool)] bool
// char* (ANSI) → string (CharSet.Ansi)
// wchar_t* → string (CharSet.Unicode)
// void* → IntPtr
// size_t → UIntPtr
// Example with explicit marshalling:
[DllImport("libc", EntryPoint = "strlen", CharSet = CharSet.Ansi)]
private static extern UIntPtr StrLen(
[MarshalAs(UnmanagedType.LPStr)] string s);
int len = (int)StrLen("hello"); // 5Passing Structs to Native Code
Use [StructLayout(LayoutKind.Sequential)] to ensure the struct is laid out in memory exactly as the native code expects.
// C struct:
// struct Point { int x; int y; };
// void DrawPoint(struct Point p);
[StructLayout(LayoutKind.Sequential)]
public struct Point
{
public int X;
public int Y;
}
[DllImport("graphics", EntryPoint = "DrawPoint",
CallingConvention = CallingConvention.Cdecl)]
private static extern void DrawPoint(Point p);
// Pass by value:
DrawPoint(new Point { X = 10, Y = 20 });
// Pass by pointer (ref or out):
[DllImport("graphics", EntryPoint = "GetCenter",
CallingConvention = CallingConvention.Cdecl)]
private static extern void GetCenter(out Point center);
GetCenter(out var pt);Error Handling: GetLastWin32Error
Windows API functions signal errors via GetLastError(). Set SetLastError = true in [DllImport] and call Marshal.GetLastWin32Error() after the call.
[DllImport("kernel32.dll",
EntryPoint = "CreateFileW",
CharSet = CharSet.Unicode,
SetLastError = true)]
private static extern IntPtr CreateFile(
string fileName,
uint desiredAccess,
uint shareMode,
IntPtr securityAttributes,
uint creationDisposition,
uint flagsAndAttributes,
IntPtr templateFile);
const uint GENERIC_READ = 0x80000000;
const uint OPEN_EXISTING = 3;
var handle = CreateFile("test.txt", GENERIC_READ, 0,
IntPtr.Zero, OPEN_EXISTING, 0, IntPtr.Zero);
if (handle == (IntPtr)(-1))
{
int error = Marshal.GetLastWin32Error();
throw new System.ComponentModel.Win32Exception(error);
}Marshalling Strings and Buffers
String marshalling requires careful attention to encoding and ownership. Use StringBuilder for output buffers and MarshalAs attributes to specify encoding.
// Read into a buffer:
[DllImport("kernel32.dll",
EntryPoint = "GetComputerNameW",
CharSet = CharSet.Unicode,
SetLastError = true)]
private static extern bool GetComputerName(
System.Text.StringBuilder lpBuffer,
ref uint nSize);
uint size = 256;
var buffer = new System.Text.StringBuilder((int)size);
if (GetComputerName(buffer, ref size))
Console.WriteLine(buffer.ToString());
// Return a string owned by native code (don't free it):
[DllImport("mylib", CharSet = CharSet.Ansi)]
[return: MarshalAs(UnmanagedType.LPStr)]
private static extern string GetVersion();Function Pointers and Callbacks
Pass managed delegates as C function pointers. The CLR creates a thunk, but you must keep the delegate alive (hold a reference) or the GC will collect it and the native code will crash.
// C callback signature: typedef int (*Comparer)(const void*, const void*);
// void qsort(void* base, size_t nitems, size_t size, Comparer compar);
[UnmanagedFunctionPointer(CallingConvention.Cdecl)]
private delegate int CompareCallback(IntPtr a, IntPtr b);
[DllImport("libc", CallingConvention = CallingConvention.Cdecl)]
private static extern void QSort(
int[] data, UIntPtr count, UIntPtr size, CompareCallback compare);
// Keep the delegate ALIVE for the duration of the call:
private static readonly CompareCallback _compare =
(a, b) => Marshal.ReadInt32(a).CompareTo(Marshal.ReadInt32(b));
var data = new[] { 5, 2, 8, 1, 3 };
QSort(data, (UIntPtr)data.Length, (UIntPtr)sizeof(int), _compare);NativeLibrary API
The NativeLibrary class provides explicit library loading, function pointer resolution, and cross-platform path customization — the modern alternative to magic library name resolution.
using System.Runtime.InteropServices;
// Explicit load:
var handle = NativeLibrary.Load("/usr/lib/libssl.so.3");
// Resolve a function pointer:
var addPtr = NativeLibrary.GetExport(handle, "AddNumbers");
var addFn = Marshal.GetDelegateForFunctionPointer<Func<double,double,double>>(addPtr);
double result = addFn(1.0, 2.0);
// Unload:
NativeLibrary.Free(handle);
// Custom resolver (called when DllImport can't find a library):
NativeLibrary.SetDllImportResolver(typeof(MyNative).Assembly,
(libName, assembly, searchPath) =>
{
if (libName == "mymath")
return NativeLibrary.Load("/opt/mymath/libmymath.so");
return IntPtr.Zero;
});Real-World: Calling OpenSSL
A real-world example: calling OpenSSL's SHA-256 digest function from C# using P/Invoke.
internal static class OpenSslInterop
{
[DllImport("libssl", CallingConvention = CallingConvention.Cdecl)]
private static extern IntPtr EVP_MD_CTX_new();
[DllImport("libssl", CallingConvention = CallingConvention.Cdecl)]
private static extern void EVP_MD_CTX_free(IntPtr ctx);
[DllImport("libssl", CallingConvention = CallingConvention.Cdecl)]
private static extern IntPtr EVP_sha256();
[DllImport("libssl", CallingConvention = CallingConvention.Cdecl)]
private static extern int EVP_DigestInit_ex(IntPtr ctx, IntPtr type, IntPtr engine);
// In practice, use System.Security.Cryptography.SHA256 instead:
// var hash = SHA256.HashData(data);
// P/Invoke to OpenSSL is only needed when you require
// non-managed cryptographic operations or specific OpenSSL features
}Quick Check
Why must you keep a delegate alive when passing it as a native callback?
Recap: P/Invoke Fundamentals
Key takeaways:
- P/Invoke: call native C-ABI functions via
[DllImport]declarations - The CLR marshals primitive types automatically; annotate with
[MarshalAs]for strings and custom types [StructLayout(LayoutKind.Sequential)]: ensure struct memory layout matches native expectations- Set
SetLastError = true+ callMarshal.GetLastWin32Error()for Win32 error handling - Keep delegate references alive when passing as native callbacks
NativeLibrary: explicit load, resolve, and custom resolver for cross-platform path control
Frequently asked questions
Is the “P/Invoke Fundamentals” lesson free?
Yes — the full text of “P/Invoke Fundamentals” is free to read here on the web, and the C# Academy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the C# Academy course, upgrade to CoddyKit PRO.
What will I learn in “P/Invoke Fundamentals”?
Declare and call native functions using DllImport, understand marshaling primitives, strings, and structs. You practise C# Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.
Do I need any experience to start C# Academy?
No prior experience is required. C# Academy on CoddyKit is structured for beginners through advanced learners; this is — lesson 1 of 4, so you can start here or from the beginning and move at your own pace.
How long does the “P/Invoke Fundamentals” lesson take?
Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.
Can I write and run code in this C# Academy lesson?
Yes. Every C# Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.