Win32 interop and the pitfalls
WinForms exposes a great deal of Windows, and not all of it. A title bar colour, a global hotkey, a file association, a window that snaps to another application: each is a call into a DLL that the base library does not wrap. C# reaches it with DllImport, and the hard part is never the call: it is the types, the marshalling and the error handling around it.
A P/Invoke signature
DllImport names a library and a function, and extern declares the managed signature without a body. The runtime loads the library on the first call, finds the export, and marshals the arguments:
internal static class Native
{
public const int DwmwaUseImmersiveDarkMode = 20;
[DllImport("dwmapi.dll")]
public static extern int DwmSetWindowAttribute(IntPtr hwnd, int attribute, ref int value, int size);
[DllImport("user32.dll", SetLastError = true)]
[return: MarshalAs(UnmanagedType.Bool)]
public static extern bool GetWindowRect(IntPtr hWnd, out RECT rect);
[StructLayout(LayoutKind.Sequential)]
public struct RECT
{
public int Left;
public int Top;
public int Right;
public int Bottom;
}
}
Every part of that block is a decision. IntPtr is an HWND: a handle is pointer-sized, so it is an IntPtr and never an int. ref int passes the address of a managed int, which works because the callee writes exactly four bytes and does not keep the pointer. out RECT is a struct passed by address, and its StructLayout must match the native layout field for field. SetLastError = true tells the runtime to capture the Win32 error before the managed code can overwrite it. And MarshalAs(UnmanagedType.Bool) is required on the return value: a C# bool is one byte, a Win32 BOOL is four, and without the attribute the upper bytes are undefined.
The DwmSetWindowAttribute line is the modern way to ask for a dark title bar on Windows 10 and 11: attribute 20, a value of 1, and the call before the window is shown. It returns an HRESULT, so a real application checks it and does nothing when the call fails, which is what an older Windows does.
A form that calls the shell
The whole program, with the signature above and a form that calls it in its constructor. Handle is read there on purpose: the call needs a window handle, and reading the property creates it. Built and not run:
using System;
using System.Drawing;
using System.Runtime.InteropServices;
using System.Windows.Forms;
internal static class Program
{
[STAThread]
private static void Main()
{
ApplicationConfiguration.Initialize();
Application.Run(new Form1());
}
}
internal static class Native
{
public const int DwmwaUseImmersiveDarkMode = 20;
[DllImport("dwmapi.dll")]
public static extern int DwmSetWindowAttribute(IntPtr hwnd, int attribute, ref int value, int size);
[DllImport("user32.dll", SetLastError = true)]
[return: MarshalAs(UnmanagedType.Bool)]
public static extern bool GetWindowRect(IntPtr hWnd, out RECT rect);
[StructLayout(LayoutKind.Sequential)]
public struct RECT
{
public int Left;
public int Top;
public int Right;
public int Bottom;
}
}
internal sealed class Form1 : Form
{
public Form1()
{
Text = "Dark title";
ClientSize = new Size(380, 140);
var dark = 1;
Native.DwmSetWindowAttribute(
Handle,
Native.DwmwaUseImmersiveDarkMode,
ref dark,
sizeof(int));
Controls.Add(new Label
{
Text = "The title bar asked for the dark mode.",
AutoSize = true,
Location = new Point(16, 20),
});
}
}
dotnet build app.csproj
Build succeeded.
0 Warning(s)
0 Error(s)
The listing is built and not run. It compiles on Linux because a DllImport declaration is metadata: nothing is loaded until the method is called, and the call happens only when the form is constructed, which needs Windows. That is the honest boundary of this page: the compiler checks the signature, and only a Windows run can check the call.
The signature as metadata
The declaration itself can be inspected, and that part runs here. The program reads the DllImportAttribute of the method, prints what it says, and asks Marshal for the sizes of the types. It was built and run in the container:
using System;
using System.Reflection;
using System.Runtime.InteropServices;
Console.WriteLine("the metadata of one P/Invoke signature");
var method = typeof(Native).GetMethod(nameof(Native.GetWindowRect))!;
var import = method.GetCustomAttribute<DllImportAttribute>()!;
var marshal = method.ReturnParameter.GetCustomAttribute<MarshalAsAttribute>();
Console.WriteLine($"library: {import.Value}");
Console.WriteLine($"entry point: {import.EntryPoint ?? "(the method name)"}");
Console.WriteLine($"charset: {import.CharSet}");
Console.WriteLine($"set last error: {import.SetLastError}");
Console.WriteLine($"return as: {marshal?.Value}");
Console.WriteLine($"RECT: {Marshal.SizeOf<RECT>()} bytes");
Console.WriteLine($"bool: {Marshal.SizeOf<bool>()} bytes");
Console.WriteLine($"IntPtr: {IntPtr.Size} bytes");
internal static class Native
{
[DllImport("user32.dll", SetLastError = true)]
[return: MarshalAs(UnmanagedType.Bool)]
public static extern bool GetWindowRect(IntPtr hWnd, out RECT rect);
}
[StructLayout(LayoutKind.Sequential)]
internal struct RECT
{
public int Left;
public int Top;
public int Right;
public int Bottom;
}
dotnet run
the metadata of one P/Invoke signature
library: user32.dll
entry point: GetWindowRect
charset: None
set last error: True
return as: Bool
RECT: 16 bytes
bool: 4 bytes
IntPtr: 8 bytes
The output is the real run, and it explains the attributes. The entry point is the method name because no EntryPoint was given; a renamed export needs one. CharSet = None is the default, which the runtime treats as ANSI for a name without W or A; a string parameter should say CharSet.Unicode or name the W export, or the call fails with an entry point that does not exist. bool is four bytes to Marshal.SizeOf, which is a Win32 BOOL and not a C# bool; that is the number behind the MarshalAs. RECT is four ints, sixteen bytes, in declaration order.
A call on this machine
What happens when the call is made where the library does not exist? The next program asks for the foreground window. It was built and run here, and the first line of the exception is the answer:
using System;
using System.Runtime.InteropServices;
Console.WriteLine("calling a Windows function on this machine");
try
{
var foreground = Native.GetForegroundWindow();
Console.WriteLine($"foreground window: {foreground}");
}
catch (DllNotFoundException error)
{
var lines = error.Message.Split('\n');
Console.WriteLine($"{error.GetType().Name}: {lines[0]}");
Console.WriteLine($"the message continues with {lines.Length - 1} paths it tried");
}
internal static class Native
{
[DllImport("user32.dll")]
public static extern IntPtr GetForegroundWindow();
}
dotnet run
calling a Windows function on this machine
DllNotFoundException: Unable to load shared library 'user32.dll' or one of its dependencies. In order to help diagnose loading problems, consider using a tool like strace. If you're using glibc, consider setting the LD_DEBUG environment variable:
the message continues with 13 paths it tried
The output is the real run. The message names the library and then lists every path the loader tried, thirteen of them on this machine; the program prints the first line and the count, because the list is long and machine-specific. On Windows the same call returns the handle of the window in front, and the failure would be a different one: EntryPointNotFoundException for a wrong name, MarshalDirectiveException for a signature the marshaller cannot satisfy, or a wrong value and a Win32Exception read through Marshal.GetLastWin32Error().
Marshalling rules
- Handles are IntPtr, never int, and a handle that has a lifetime is a SafeHandle subclass in modern code.
- Structs are explicit: LayoutKind.Sequential, the fields in native order, and the sizes checked with Marshal.SizeOf.
- BOOL is four bytes: [return: MarshalAs(UnmanagedType.Bool)] on the return and on any BOOL parameter.
- Strings are encoding: CharSet.Unicode for the W exports, and StringBuilder or a size-checked buffer only when the callee writes into it.
- Errors are explicit: SetLastError = true and Marshal.GetLastWin32Error() immediately after the call; the runtime clears the value.
- Architecture matters: a win-x86 build calls the 32-bit DLLs, and a handle is four bytes there. The same source compiles to both, which is why IntPtr.Size is checked and never assumed.
- Do not guess a signature: a wrong one corrupts the stack or the heap, and the crash appears later. Copy it from the platform documentation or the source of the wrapper library.
The modern alternative is LibraryImport, a source generator that writes the marshalling code at build time and is the recommended form for new interop. It requires AllowUnsafeBlocks and a partial method, and it fails at build time on a signature it cannot generate, which is the improvement worth having. The signatures above are written with DllImport because that is what the existing WinForms code uses, and because the reflection of the previous program is about DllImportAttribute.
Exercises
- Read the window rectangle with GetWindowRect in a form and print the four numbers into a label; say what a failed call returns.
- Change the metadata program to print the CallingConvention and the parameter names of the method.
- Rewrite one signature as a LibraryImport partial method and explain what the generator needs to know.
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
When is the native library loaded?
Answer
On the first call of the method
The declaration is metadata until the call.
-
Why is a window handle an IntPtr?
Answer
A handle is pointer-sized, four bytes on x86 and eight on x64
An int truncates a 64-bit handle.
-
What does SetLastError = true do?
Answer
Captures the Win32 error before managed code can overwrite it
The value is read with Marshal.GetLastWin32Error.
-
How large is a Win32 BOOL in the run?
Answer
4 bytes
Marshal.SizeOf printed 4 for bool with the attribute.
-
What did the metadata program report for the entry point?
Answer
GetWindowRect, the method name
No EntryPoint was given, so the method name is used.
-
Which exception did the call on Linux throw?
Answer
DllNotFoundException
The loader could not find user32.dll and listed the paths it tried.
-
Why does a wrong CharSet matter?
Answer
It selects the A or W export, and the wrong name does not exist
The exported function name carries the character set.
-
What should be read immediately after a failing call with SetLastError?
Answer
Marshal.GetLastWin32Error()
The runtime clears the error value on the next call.
-
What is dangerous about guessing a signature?
Answer
It corrupts the stack or heap and crashes later
The marshaller trusts the declaration.
-
Which form is recommended for new interop?
Answer
LibraryImport, generated at build time
It generates marshalling code and fails at build time on a bad signature.
Every listing on this page was built with the .NET SDK 10.0.303 for net10.0-windows against the targeting pack Microsoft.WindowsDesktop.App.Ref 10.0.15 from the offline feed, in a Docker container on Alpine Linux 3.24.3 (x86_64). The programs were built, not run on Linux: WinForms needs Windows. The logic that draws nothing was also run headless on the same machine, and its output is the run output printed below each of those programs.
Article author: Arthur Isaev