Choosing Between DllImport and LibraryImport When NativeAOT Strips Your Metadata

You've got a native library to call. Old habit: write a DllImport declaration, decorate with MarshalAs, and call it a day. But then you flip on NativeAOT, your app compiles, launches — and the first P/Invoke call throws an EntryPointNotFoundException. Or worse, it silently returns garbage.

Metadata is the culprit. NativeAOT strips IL metadata that the runtime uses to resolve and marshal P/Invoke calls at runtime. LibraryImport, the source-generated alternative introduced in .NET 7, sidesteps the problem entirely — at the cost of some flexibility. But the choice isn't binary. There are edge cases, versioning concerns, and real-world traps that make this decision harder than a simple rule of thumb.

Where This Bites You: Real-World Field Context

The 3 AM Phone Call: When Metadata Stripping Becomes a Production Event

I got the call at 2:47 AM. A .NET service that had been running fine for weeks — deployed as a NativeAOT binary on a Linux container — suddenly couldn't load a third-party PDF library. The error? Something about 'unable to find an entry point' in a native DLL that was clearly sitting in the container's file system. The library's C# wrapper used DllImport everywhere. On a regular runtime, that's fine — the runtime can reflect over the assembly, find the method signature, and resolve the native symbol at runtime.

Vendor reps rarely volunteer the maintenance interval; however boring it sounds, the calibration log is what keeps tolerance from drifting into customer returns.

But NativeAOT strips virtually all metadata during compilation. That [DllImport("libfoo.so")] declaration? It's effectively gone in the AOT image.

Operators we shadowed described three distinct failure modes — mis-threaded tension, skipped press tests, and unlabeled batches — each preventable when someone owns the checklist before the rush starts.

No metadata means no dynamic resolution. The entry point doesn't exist because the linker never saw a reason to keep it. Wrong order. We lost six hours rebuilding with LibraryImport and re-validating every interop boundary.

That outage wasn't an edge case — it's the field reality for anyone pushing NativeAOT into production. Most crews don't discover this until their service hits a staging environment or, worse, a traffic spike on Black Friday. The typical story: you migrate to NativeAOT for startup speed and smaller container sizes, run all your unit tests green, deploy to staging, and then a specific code path — often one that touches encryption, image processing, or hardware authentication — silently fails.

Skeg eddy ferry angles bite.

The catch: the same binary works perfectly on Windows but blows up on Linux, because the AOT toolchain behaves differently per platform.

Heddle selvedge weft drifts.

On Windows, the metadata-stripping is sometimes more aggressive during publish, but on Linux, the native library loading paths have fewer fallbacks. You'll see EntryPointNotFoundException or, in the worst cases, a silent crash with no stack trace — just a process exit code.

'We assumed DllImport was safe because it worked in our integration tests under the full runtime. NativeAOT turned that assumption into a production incident.'

— Senior backend engineer, on-call during a payment-service outage in 2024

The NuGet Trap: How Third-Party Packages Become Liability

What usually breaks first isn't your own code — it's a NuGet package you don't control. I've seen this pattern repeat: a team pulls in a popular interop library like SkiaSharp, libgit2sharp, or a hardware SDK wrapper. The package works fine for years on regular .NET. Then they turn on NativeAOT. Suddenly, every DllImport in that dependency is a ticking bomb. The package author didn't mark the methods with DisableRuntimeMarshalling or provide LibraryImport alternatives. You can't patch upstream. And because NativeAOT strips metadata, you can't even use [DynamicDependency] attributes to force the linker to keep those interop methods — the attribute hints only work for the trimmer, not for the actual AOT compilation step that eliminates the native-to-managed glue code entirely.

The cross-platform differences compound this. On Windows, the NativeAOT toolchain still generates some interop stubs for Win32 API calls because the platform-specific code paths are more thoroughly tested. On Linux, many of those same stubs get pruned. I've debugged a case where a DllImport to libc.so worked in an Azure Container Apps instance running Ubuntu 22.04 but failed on a Debian 11-based container — because the symbol resolution path differed and the AOT linker had eliminated the marshalling code for that specific function signature. That hurts. The fix? Rewriting every interop call to LibraryImport with explicit MarshalAs attributes, then re-running the entire suite on every target OS. Most groups budget two weeks for that migration. Some find hidden dependencies they didn't know existed.

What They Don't Tell You About DllImport and LibraryImport

How DllImport Resolves Methods at Runtime

Most crews never look under the hood until something burns. `DllImport` feels simple: you slap a string for the DLL name, a `static extern` signature, and the runtime handles the rest. But 'handles' is doing heavy lifting here. Under NativeAOT, that attribute relies on metadata tokens embedded in your assembly — the runtime walks those tokens at startup to locate the unmanaged function pointer. If NativeAOT strips that metadata (and it will, aggressively), the linker can't prove the method is reachable. Gone. You get a crash at the entry point, sometimes a cryptic `EntryPointNotFoundException` or just a silent hang. I have seen teams spend two days debugging a `DllImport` on a Raspberry Pi only to realize the linker had optimized their P/Invoke into a ghost. The assumption that 'it compiles, so it works' is the expensive one here.

LibraryImport's Source-Generation Pipeline

`LibraryImport` takes a different path entirely — one that doesn't care about runtime metadata. At compile window, a source generator reads the attribute and produces C# code that directly marshals parameters and calls `GetProcAddress` or `dlsym`. No metadata lookup at runtime. That means NativeAOT can safely strip the entire reflection infrastructure, because the generated code already holds the function pointer. The catch? You trade runtime flexibility for compile-phase certainty. `LibraryImport` demands a compile-phase constant for the DLL name and entry point — no `Marshal.GetDelegateForFunctionPointer` shenanigans later. That bites teams who rely on conditional loading per platform. 'But it works in Debug mode on my desktop' — wrong order. Most teams skip this: run the AOT build *before* you finish the feature, not after.

False Sense of Compatibility with Partial Trimming

Here is where the trap springs. You enable 'partial trimming' or set `true` in a non-AOT project — things limp along. The linker may keep enough metadata to satisfy a `DllImport` call, especially if you haven't hit the strictest trimming level. That builds a dangerous assumption: 'My DllImport works trimmed, so NativeAOT will be fine.' It won't. NativeAOT runs a fundamentally different linker that *removes* the metadata model entirely — there is no 'keep enough for DllImport' mode. What survives in partial trimming is often a coincidence, not a guarantee. The seam blows out when you ship to an embedded device or an ARM64 server image. One concrete anecdote: a colleague shipped a monitoring agent using `DllImport` with `CallingConvention = Cdecl` and partial trimming. Worked for months. NativeAOT stripped it to a segfault at boot. The fix was rewriting six call sites to `LibraryImport` and adding a manual verification step in CI that runs the AOT link check. — That hurt.

'DllImport is legacy support for the full runtime. LibraryImport is the contract for the AOT future — but the contract comes with fine print.'

— paraphrased from a .NET runtime engineer during a 2023 community standup

The practical cost here isn't just a broken build. It's the trust erosion — you stop believing your linker settings, you start second-guessing every `extern` method, and you waste cycles adding `[DynamicDependency]` annotations that you never needed before. That's the maintenance tax that doesn't show up on day one. It arrives six months later, when a junior dev copies a pattern from Stack Overflow that worked in a unit test but fails under full AOT. What usually breaks first is not the obvious stuff — it's the helper library that loads vendor DLLs via string-based `DllImport` at runtime. You'll see it in production logs before anyone thinks to check the linker configuration.

Patterns That Actually Survive NativeAOT

Using LibraryImport with Blittable Types

The safest bet for NativeAOT survival is keeping your P/Invoke signatures purely blittable—structs that look identical in managed and unmanaged memory, no marshaling strings, no arrays of objects. I've seen teams cling to DllImport because "it's always worked," then watch their whole interop layer silently return garbage after trimming. LibraryImport with a blittable signature?

Vendor reps rarely volunteer the maintenance interval; however boring it sounds, the calibration log is what keeps tolerance from drifting into customer returns.

The source generator emits all marshaling code at compile time.

Operators we shadowed described three distinct failure modes — mis-threaded tension, skipped press tests, and unlabeled batches — each preventable when someone owns the checklist before the rush starts.

No runtime reflection, no metadata falls through the cracks. That's the baseline pattern you should default to.

Reality check: name the development owner or stop.

Reality check: name the development owner or stop.

Consider a simple OS call: reading disk sector info. A DllImport version with out long and ref int works—until it doesn't, because the runtime can't locate the metadata for parameter size at link time. Rewrite it with LibraryImport, keep arguments as raw long, int, and fixed-size struct—that survives AOT stripping. The catch? You lose automatic string marshaling. string parameters in LibraryImport require explicit MarshalAs attributes, and even then, only ANSI or UTF-16 charsets are guaranteed. Your UTF-8-only APIs will need a different approach. That's the trade-off: safety for convenience.

Most teams skip this: test the blittable boundary early. Write a minimal struct with LayoutKind.Sequential and a single int field—pass it across, see if the AOT-compiled binary keeps the bytes in order. What usually breaks first is alignment padding, or bool mapped to 1 byte instead of 4. Fix that with MarshalAs(UnmanagedType.U1) or I1, and you're solid. Honestly—it's boring work, but it's the kind of boring that ships.

Explicit Marshaling with Custom Source Generators

Blittable-only is a nice ideal. Real-world interop needs strings, variable-length arrays, or COM-like interfaces. That's where LibraryImport alone won't cut it. The trick is writing a custom source generator that handles the non-blittable marshaling DllImport used to do at runtime—but baked into the binary. I've done this for a Win32 API that expected LPWSTR output buffers: the source generator allocates the char[], pins it, calls the native function, then copies the result back. No metadata required. The generated code is ugly, but it's predictable.

Wrong order here kills you: you can't fall through to DllImport as a fallback. If your generator emits a DllImport under the hood, the NativeAOT linker still sees the metadata dependency and strips it. Instead, have the generator emit raw [UnmanagedCallersOnly] wrappers that call Marshal.GetFunctionPointerForDelegate—that pattern survives trimming because it resolves the pointer at compile time. The cost? More boilerplate per API call. One concrete anecdote: we had 30 interop points in a telemetry agent; rewriting 10 critical ones with a custom generator took two days. The remaining 20 stayed on DllImport and crashed in staging. We fixed those too. That hurts.

A rhetorical question: isn't a custom generator overkill for three string parameters? Maybe. But losing a day to a heisen-crash in production is worse than a day writing generator code. The maintenance tax shifts from runtime debugging to compile-time logic. Some teams prefer that trade.

'The generated code is ugly, but it's predictable—and predictability beats elegance when your binary has no fallback.'

— observation from a telemetry agent rewrite

Conditional Compilation for Dual-Targeting

You don't have to commit exclusively to NativeAOT on day one. The pragmatic pattern is dual-targeting: use #if NET8_0_OR_GREATER and #if !NATIVEAOT to toggle between LibraryImport (safe, fast) and DllImport (flexible, legacy). I've seen this work well in libraries that ship to both desktop apps and AOT-compiled cloud services. The LibraryImport path uses blittable structs or generated marshaling; the DllImport path keeps the old string and object parameters for JIT-based runtimes. Two code paths, one source file.

The pitfall? Keeping both paths in sync. Add a field to a struct—update both versions. Forget, and the AOT path crashes while the JIT path works fine, or vice versa. That's a variant of the maintenance tax, but it's usually lower than rewriting everything at once. What I'd suggest: start every new interop call as LibraryImport with a blittable signature. Only fall back to DllImport with conditionals when you genuinely can't avoid non-blittable types. The seam blows out faster when you treat the two attributes as interchangeable—they're not. One generates code at compile time; the other expects runtime metadata. That gap doesn't shrink.

End with a specific next action: pick one interop call in your current project—one that uses string or object[]—and rewrite it as a blittable LibraryImport with a fixed-size byte buffer instead. Test under NativeAOT. If it works, that's your template. If it doesn't, then add the custom generator. Either way, you've got a proven pattern, not a guess.

Anti-Patterns That Look Fine but Crash Later

Hidden MarshalAs attributes that DllImport needs

The cleanest DllImport you'll ever write looks like this—a plain string parameter, no marshaling hints, and it compiles without a warning under NativeAOT. That's the trap. NativeAOT strips metadata aggressively, and the runtime binder can't fall back to IL-level analysis when your P/Invoke needs an explicit character set or a size-constrained buffer. I've debugged a production crash where a BOOL return value silently became garbage on ARM64 because the default MarshalAs(UnmanagedType.Bool) got optimized away during trimming. The seam blows out not during the first call—that works in testing—but at month two, on a customer machine with different locale settings, when the runtime finally hits a code path that relied on the stripped metadata. You fix it by spelling everything out: [MarshalAs(UnmanagedType.LPWStr)], [In, Out] on array parameters, and never trusting the CharSet.Auto default to survive the linker.

StringBuilder parameters (still a trap)

Yes, it's 2025 and StringBuilder still breaks under NativeAOT like it's 2005. The pattern looks innocent—pass a pre-allocated StringBuilder to a Win32 function that writes into it—and it works fine with the full runtime because the JIT can reconstruct the buffer layout from IL metadata. NativeAOT doesn't have that luxury. The linker sees a StringBuilder parameter and, unless you've explicitly marked the capacity with [MarshalAs(UnmanagedType.LPWStr, SizeConst = 256)], it can infer zero buffer semantics. Your function returns ERROR_SUCCESS but the string is empty. Or worse: it returns an access violation three calls later because the runtime marshaled a one-byte buffer that the native code happily overwrote. We fixed this by swapping to a char[] pinned with GCHandle.Alloc—ugly, but predictable under every AOT backend. StringBuilder is syntactic sugar that rots when the metadata kitchen closes.

BestFitMapping and ThrowOnUnmappableChar defaults

Most teams skip this: the default BestFitMapping=true and ThrowOnUnmappableChar=false on DllImport are metadata-dependent behaviors. Under NativeAOT, those defaults are baked into the caller's assembly manifest—if the manifest is trimmed (and it will be), the runtime silently falls back to ASCII substitution instead of throwing. That sounds like a safety net; it's not. I've seen Japanese kanji silently replaced with '?' in file paths, corrupting data for weeks before anyone noticed, because the crash path was disabled. The fix is aggressive: always set BestFitMapping=false, ThrowOnUnmappableChar=true explicitly on every DllImport that touches text. Wrong order? That hurts. You'll lose a day diagnosing why a Korean locale produces garbage while English locales pass every unit test.

“We lost two weeks to a StringBuilder that worked in debug, crashed in release, and only under NativeAOT on Chinese Windows.”

— Lead engineer, after migrating a file-system utility library

Odd bit about development: the dull step fails first.

Odd bit about development: the dull step fails first.

The interop attribute mismatch

One anti-pattern I catch repeatedly: mixing DllImport with LibraryImport in the same assembly because the migration guide said "do them one at a time." That compiles. It even runs—until NativeAOT generates two different marshaling stubs for the same native function, one source-generated (fast, metadata-free) and one reflection-based (slow, metadata-greedy). The reflection stub gets trimmed away during publish because the linker sees the source-generated version as sufficient. Half your call sites crash with EntryPointNotFoundException at runtime, and the stack trace points to the assembly that does define the function. Each call site that uses DllImport needs its own explicit [SuppressGCTransition] or [UnmanagedCallersOnly] attribute to survive the trimmer—or you commit fully to LibraryImport in one painful refactor sprint. Partial migration is a half-bridge over a chasm.

The Maintenance Tax: Drift and Long-Term Costs

The Dual-Wrapper Trap: Maintaining Two P/Invoke Surfaces

Once you commit to both DllImport and LibraryImport paths — one for NativeAOT, one for the runtime JIT — you inherit two parallel codebases that must stay in lockstep. I have watched teams paste the same signature into two files, then watch them silently diverge over three sprints. A bool becomes [MarshalAs(UnmanagedType.Bool)] in one wrapper but not the other. A char* changes to ref char in the LibraryImport version, while the DllImport side still marshals as string. The compiler won't yell — the runtime just corrupts your stack. That's the tax. You're not writing P/Invoke once; you're writing it, duplicating it, testing it twice, and hoping nobody misses the diff in a PR that deploys at 5 PM on a Friday.

Versioning Native Libraries When Conventions Shift

What usually breaks first is not the .NET side — it's the native library that changes its calling convention between releases. We fixed this by pinning versions in our deployment pipeline, but the cost showed up elsewhere: every time the C++ team switched from cdecl to stdcall for performance, both wrapper layers needed updates. The DllImport version required a new CallingConvention enum value. The LibraryImport version needed a fresh source generator run and a rebuild. Wrong order? You deploy a broken interop seam and get a crash on the first call that crosses the boundary. That hurts. The matrix multiplies: x86 vs x64, debug vs release, Windows vs Linux. Suddenly you're maintaining eight variations of a 20-line wrapper, and the cognitive load for new hires is brutal — they can't tell which attribute applies where.

Upgrading Across .NET Versions—The Drift Accelerates

Moving from .NET 7 to .NET 9 introduced breaking changes that hit the two attributes differently. DllImport lost support for certain CharSet values in NativeAOT mode — silently falling back to ANSI instead of failing. LibraryImport got stricter about blittable types, rejecting structs that had been perfectly fine in .NET 7. So now you're not just maintaining two wrappers; you're maintaining two wrappers that evolve at different speeds under each runtime version. The catch is that nobody tests both paths until a customer ships the NativeAOT build to production. That's when the drift surfaces as a weird string corruption or a segfault that only happens on ARM64. One rhetorical question here: how many of your CI pipelines run both JIT and AOT configurations against every commit? Most teams I talk to skip that, because the build time doubles and the test matrix explodes.

“We thought choosing both attributes was being safe. It turned into two snowflakes that melted at different rates.”

— lead platform engineer at a trading firm, after rolling back to pure DllImport for their Linux AOT deployment

The long-term cost isn't just lines of code — it's the drift tax. Every quarter you pay it when a new runtime drops, when a native library bumps its ABI, or when a junior developer adds [In, Out] to one wrapper but not the other. That sounds manageable until you realize the seam blows out at 3 AM during a deployment and nobody on-call remembers which wrapper the ARM cluster runs.

When Neither Attribute Is the Right Answer

When C Varargs Force You into Manual Memory Hell

Some native APIs demand variable argument lists—think printf-style functions, event logging routines, or custom format engines. Neither DllImport nor LibraryImport can express a C va_list parameter. DllImport will let you attempt it, but the runtime won't marshal the va_list correctly—you get garbage or an access violation. LibraryImport flatly refuses: it's not part of the supported signature set. So where do you go?

The pragmatic answer: write a tiny C-side wrapper that unpacks the varargs into a fixed struct, then call that from managed code. I've done exactly this for a telemetry aggregator that logged structured events via a C library. The wrapper consumed the ... and handed back a typed buffer. Painful? Yes. But it survived NativeAOT trimming because the wrapper is a native symbol—no metadata involved. The trade-off is a maintenance boundary: every time the varargs signature changes, the wrapper must change too. Miss that update, and data gets silently corrupted.

Another escape hatch: use Marshal.GetFunctionPointerForDelegate with a manually loaded native function, then call it via VirtualProtect-style patterns. That's raw and error-prone—but sometimes it's the only bridge when both attributes bail out.

Calling Conventions That LibraryImport Won't Touch

LibraryImport is opinionated: it supports __stdcall on Windows and __cdecl on most platforms. That's it. But real-world libraries throw curveballs: __fastcall, __thiscall, or platform-specific ARM calling conventions. DllImport can be told about these via CallingConvention—though it often crashes under NativeAOT anyway, because the metadata for the custom calling convention gets stripped. The catch is that neither attribute will reliably handle __vectorcall or register-based parameter passing used by some SIMD-heavy C libraries.

Most teams skip this until the seam blows out. I watched a rendering engine silently produce wrong outputs because a __vectorcall function was called with default __cdecl marshalling. The fix? Drop both attributes entirely. We built a thin C++/CLI wrapper that exposed a flat __cdecl surface, then called that from C# using LibraryImport. Not beautiful. But it worked, and NativeAOT left the wrapper alone because it's compiled native code, not reflection-based interop.

When neither attribute speaks the ABI's dialect, the only safe interpreter is a native shim that translates calling conventions before managed code ever touches the stack.

— A respiratory therapist, critical care unit

— lesson from debugging a crash that only reproduced on ARM64, two weeks before a customer demo

Not every development checklist earns its ink.

Not every development checklist earns its ink.

When C++/CLI or COM Interop Is Actually the Cleaner Escape

Here's the uncomfortable truth: some interop scenarios are conceptually incompatible with NativeAOT's metadata-free philosophy. If your native library exposes a complex object hierarchy, callbacks via function pointers on a struct, or stateful interfaces that require manual memory management across boundaries—both DllImport and LibraryImport become liability magnets. The marshalling gets tangled, the trimming hits something unexpected, and suddenly you're debugging a crash in QCall internals. Not fun.

COM interop, for all its age, actually plays well with NativeAOT because the runtime generates RCW wrappers from IDL—no reflection needed at call time. I've seen teams abandon P/Invoke entirely for a COM-based interop layer when the native API was notification-heavy and had multiple out-parameters. The cost? You're now married to COM's lifetime rules (AddRef/Release discipline), and the setup ceremony is higher. But the benefit is a reliable boundary that NativeAOT won't silently strip.

Alternatively, a mixed-mode C++/CLI assembly gives you direct access to native headers and calling conventions. You write the glue in C++/CLI, expose a flat __cdecl surface, and call that from your AOT-compiled C#. The downside is build complexity—you need separate compilation for the mixed-mode assembly, and you lose the "single artifact" simplicity of pure managed code. But when neither DllImport nor LibraryImport can express the contract without lying to the runtime, that trade-off beats shipping crashes.

Open Questions and FAQ

Can I use DllImport with a custom assembly linker?

Technically yes—but you're walking into a metadata minefield. I've watched teams wire up a custom linker that preserves every IL stub for DllImport methods, only to find that NativeAOT's optimizer still elides the supporting marshalling infrastructure. The linker keeps the method signature; the AOT compiler discards the runtime-generated P/Invoke trampolines. That's not a linker bug—it's a contract mismatch. The custom linker preserves what you told it to preserve, but NativeAOT sees the DllImport attribute, decides "I can strip the IL-level stub," and suddenly your call site points at a ghost. The catch is you'd need to replicate roughly 70% of what LibraryImport's source generators do manually—and most teams underestimate that gap by about two sprints. Honestly, if you're already running a custom linker, you're past the point where DllImport makes sense; switch to LibraryImport or accept that you'll be maintaining a private fork of the runtime's marshalling logic.

Does LibraryImport support all the MarshalAs attributes?

No, and the gaps are weird. LibraryImport handles the common cases—UnmanagedType.LPStr, UnmanagedType.LPWStr, UnmanagedType.Bool with proper size mapping—but I've hit hard stops on custom marshalling with UnmanagedType.CustomMarshaler. The source generator simply refuses to compile that combination, and the error message reads like a puzzle: "Custom marshalling is not supported." No workaround, no fallback path. What usually breaks first is anything involving UnmanagedType.ByValArray combined with a fixed size—LibraryImport can do it, but the generated code sometimes misaligns the buffer offset by a few bytes. That's an edge case that only surfaces when your interop buffer crosses a page boundary. Most teams skip this by falling back to DllImport for those few signatures. It's ugly—you end up with a mixed-bag interop layer—but it beats shipping a crash that only repros on ARM64 under load.

'LibraryImport is the future, but the future still has a few unlit alleyways.'

— lead engineer, after debugging a misaligned struct for six hours

What about .NET 8's improved trimming analyzers?

They're better, but not smart. .NET 8's trim analyzer will warn you when a DllImport method references types that NativeAOT can't preserve—things like dynamic assembly loading or reflection-based marshalling. That's helpful; it catches the obvious death-spirals. The problem is the analyzer operates on a static model: it flags potential issues, not actual runtime behaviour. I've seen code pass the analyzer cleanly, hit production, and then throw a MissingMethodException because a nested struct's layout relied on a field offset that NativeAOT recalculated differently. The trim analyzer doesn't understand Win32 API conventions—it doesn't know that your GetProcAddress fallback will never be called, so it warns about it anyway, drowning out real signals. What we fixed internally was adding a suppression file that silences known-safe patterns and then running a separate AOT-specific integration test suite. Not elegant, but it cut our false-positive noise by roughly 60%. The roadmap for .NET 9 promises tighter integration between the trim analyzer and the source generator; I'll believe it when I see a build pass without three pages of yellow squiggles.

One open question nobody's answered cleanly: what happens when LibraryImport's generated code hits a type that used to be blittable but isn't after NativeAOT's layout reordering? That's not theoretical—we've seen it with System.Guid on certain runtime versions. The source generator assumes a fixed layout; NativeAOT doesn't always honour it. Until the toolchain aligns those two assumptions, you keep a manual struct-layout test in your pipeline. Not a disaster. But it's the kind of maintenance tax that makes you question whether interop was worth the abstraction in the first place.

Summary and Next Experiments

Decision flowchart: which attribute to choose

You don't need a PhD in the runtime to pick a side. The rule is brutal but simple: if your interop target must run on full-framework .NET or Mono (Xamarin, Unity IL2CPP), you're stuck with DllImport — LibraryImport doesn't exist there. But if you control the whole deployment stack and NativeAOT is on the table, LibraryImport wins every time. Why? It generates the marshalling stubs at compile time. No reflection, no runtime metadata lookup, no late-binding surprises when the linker gutted your assembly. I have seen teams waste two sprints debugging a 'random' EntryPointNotFoundException that only repros on trimmed builds — that's the DllImport metadata trap. The catch: LibraryImport won't let you pass string with CharSet.Auto and expects you to handle bool as explicit MarshalAs. Trade-offs, always.

Testing your interop layer with NativeAOT early

Most teams skip this: they write interop code, test on desktop runtime, then send the whole thing to production with NativeAOT enabled. Wrong order. The minute you add a DllImport for a C function that returns a struct by value, you need to compile with PublishAot=true and see if the linker silently drops the P/Invoke metadata. We fixed this by adding a CI step: compile the app as NativeAOT, then run a simple smoke test that calls every external function once. That catches 90% of the metadata-stripping cases. What usually breaks first? Functions with [In, Out] arrays of blittable structs — the AOT compiler may reject the implicit marshalling. Another pitfall: SetLastError=true on LibraryImport requires you to call Marshal.GetLastPInvokeError() instead of Marshal.GetLastWin32Error(). Small diff, huge crash.

Monitoring for metadata-related crashes in production

You pushed to prod. Everything looks green. Then, three days later, a spike of TypeLoadException or MissingMethodException from a specific OS version. That's the metadata seam blowing out. Monitor for System.ArgumentException with messages containing 'Could not load type' or 'Void' in the call stack — those are the fingerprints of a method that the AOT compiler couldn't resolve. Honest advice: add structured logging around any interop call that returns HRESULT or errno. The symptom won't be a crash in your C# code; it'll be a silent failure in the native layer because your marshalling was stripped to a stub that always returns 0. One team I consulted saw random file-write failures for weeks — turned out DllImport for WriteFile had its calling convention lost during trimming, and the arguments shifted by one register. That hurts.

'We switched to LibraryImport and the 'random' crashes vanished. The only cost was rewriting three struct definitions to avoid automatic layout.'

— Lead engineer on a Windows service migration, after three weeks of root-cause churn

Next experiment: grab your top ten most-called native functions, rewrite them as LibraryImport, compile with NativeAOT, and run them under a memory profiler. Compare the IL size and the startup time. You'll likely see a 12–18% reduction in assembly size for those wrappers alone. Not yet convinced? Take the same functions, mark them DllImport with ExactSpelling=true and CharSet=CharSet.Ansi, then do the same test. The difference in generated code is stark. That's your decision data — not theory, not docs, just your own build output.