在 .NET 中调用 C/C++ 原生库并排查边界崩溃…

从 .NET 调用 C/C++ 原生库时，按目标框架选择 DllImport 或 LibraryImport，并正确处理类型映射、字符串编码、内存所有权、SafeHandle、回调和跨平台加载。

适用场景

解决思路

1. 根据目标框架选择：.NET Framework 始终用 DllImport；.NET 7+ 新代码优先用 LibraryImport；需要 native AOT 时 LibraryImport 是唯一选项。
2. 开始前收集：原生头文件或文档、目标框架、目标平台、内存所有权契约；当文档与原生头文件冲突时，始终信任头文件。
3. 如果只涉及单个函数：只做签名映射（步骤 1-3），仅在相关时处理字符串/内存，跳过工具和迁移部分。
4. 不要迁移现有 DllImport 到 LibraryImport，除非用户要求或 AOT/trimming 是明确需求。
5. 不要推荐 CsWin32，除非目标就是 Win32 API。
6. 不要生成回调，除非原生 API 需要函数指针。
7. 如果请求是审查，使用验证清单，不要重写可工作代码。
8. 映射原生类型到 .NET 类型：C long 用 CLong；size_t 用 nuint（.NET 8+）或 UIntPtr（更早 .NET），绝不用 ulong；Win32 BOOL 用 int，不用 bool；C99 bool 用 [MarshalAs(UnmanagedType.U1)] bool；HANDLE、HWND 用 SafeHandle；LPWSTR/wchar_t* 用 string，但注意 Windows 是 UTF-16，跨平台避免因为 wchar_t 宽度由编译器定义（非 Windows 通常 UTF-32）；LPSTR/char* 用 string，并且必须指定 encoding（ANSI 或 UTF-8）。
9. 绝不使用 int 或 long 表示 C long：它在 Windows 上是 32 位、在 Unix 上是 64 位，始终用 CLong。绝不使用 ulong 表示 size_t：在 32 位会导致栈损坏，用 nuint 或 UIntPtr。绝不使用没有 MarshalAs 的 bool：默认 marshal 大小错误。
10. 遇到 Step 2 未覆盖的类型、结构体布局或 blittable 类型规则时，加载 references/type-mapping.md 获取完整原生到 .NET 类型映射表、结构体布局模式和 blittable 规则。
11. 按 C 头文件写声明：例如 C 函数 int32_t process_records(const Record* records, size_t count, uint32_t* out_processed); 对应 DllImport 为 [DllImport("mylib")] private static extern int ProcessRecords([In] Record[] records, UIntPtr count, out uint outProcessed); 对应 LibraryImport 为 [LibraryImport("mylib")] internal static partial int ProcessRecords([In] Record[] records, nuint count, out uint outProcessed);。
12. 仅在目标为 Windows x86（32 位）时指定调用约定，因为 Cdecl 与 StdCall 不同；在 x64、ARM、ARM64 上只有一个调用约定，不需要该 attribute。
13. 如果检测到 Windows x86 目标（例如 <PlatformTarget>x86</PlatformTarget>、win-x86、构建脚本、注释或开发者说明），向开发者标记并建议所有 P/Invoke 声明显式指定调用约定：DllImport 用 [DllImport("mylib", CallingConvention = CallingConvention.Cdecl)]；LibraryImport 用 [LibraryImport("mylib")] 加 [UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]。
14. 如果托管方法名与原生导出名不同，指定 EntryPoint 以避免 EntryPointNotFoundException：DllImport 用 [DllImport("mylib", EntryPoint = "process_records")]；LibraryImport 用 [LibraryImport("mylib", EntryPoint = "process_records")]。
15. 处理字符串时：知道原生函数期望的编码，没有安全默认值；Windows API 始终调用 W（UTF-16）变体，A 变体需要特定理由并显式 ANSI 编码；跨平台 C 库通常期望 UTF-8；显式指定编码，绝不依赖 CharSet.Auto；绝不为输出缓冲区引入 StringBuilder。
16. 字符串声明示例：DllImport Windows API 用 [DllImport("kernel32.dll", CharSet = CharSet.Unicode, SetLastError = true)]；DllImport 跨平台 C 库用 [MarshalAs(UnmanagedType.LPUTF8Str)] string；LibraryImport UTF-16 用 [LibraryImport("kernel32", StringMarshalling = StringMarshalling.Utf16, SetLastPInvokeError = true)]；LibraryImport UTF-8 用 [LibraryImport("mylib", StringMarshalling = StringMarshalling.Utf8)]。
17. 字符串生命周期警告：被 marshal 的字符串在调用返回后释放；如果原生代码存储指针而不是复制，必须手动管理生命周期；在 Windows 或 .NET Framework 上，跨边界所有权首选 CoTaskMemAlloc/CoTaskMemFree；在非 Windows 目标上使用 NativeMemory API；如果库有自己的分配器，必须改用库的分配器。
18. 建立内存所有权：内存跨边界时恰好一侧拥有它，并且双方必须达成一致；绝不用不匹配的分配器释放，例如对 malloc 分配的内存调用 Marshal.FreeHGlobal 会导致堆损坏。
19. 使用模型 1——调用方分配、调用方释放（最安全）：声明 GetName(Span<byte> buffer, nuint bufferSize, out nuint actualSize)；实现中用 stackalloc byte[256]，调用 GetName(buffer, (nuint)buffer.Length, out nuint actualSize)，检查 result != 0 抛异常，最后用 Encoding.UTF8.GetString(buffer[..(int)actualSize])。
20. 使用模型 2——被调用方分配、调用方释放（Win32 常见）：声明 GetVersion() 返回 IntPtr 和 FreeString(IntPtr s)；调用后用 try { return Marshal.PtrToStringUTF8(ptr) ?? throw new InvalidOperationException(); } finally { FreeString(ptr); }；必须用库自己的 free 函数。
21. 使用模型 3——基于句柄（被调用方分配、被调用方释放）：使用 SafeHandle。
22. 固定托管对象：同步时用 fixed { ProcessData(ptr, (nuint)data.Length); }；异步时用 GCHandle.Alloc(data, GCHandleType.Pinned)，并保持 pinned 直到原生处理完成，然后调用 gcHandle.Free()。
23. 对原生句柄使用 SafeHandle：裸 IntPtr 会在异常时泄漏且没有双重释放保护，SafeHandle 是不可协商的；实现 internal sealed class MyLibHandle : SafeHandleZeroOrMinusOneIsInvalid。
24. SafeHandle 实现细节：private MyLibHandle() : base(ownsHandle: true) { } 是 marshalling 基础设施实例化句柄所必需的，不要移除；声明 LibraryImport 的 CreateHandle、UseHandle、DestroyHandle；ReleaseHandle() 调用 DestroyHandle(handle) 并返回 true；Create 方法检查 h.IsInvalid 后抛异常；Use 方法调用 UseHandle(this, data, (nuint)data.Length)；使用 using var handle = MyLibHandle.Create("config=value");。
25. 处理错误：Win32 API 用 [LibraryImport("kernel32", SetLastPInvokeError = true)] 和 [return: MarshalAs(UnmanagedType.Bool)]，失败时抛 new Win32Exception(Marshal.GetLastPInvokeError())；HRESULT API 用 int hr = NativeDoWork(context); Marshal.ThrowExceptionForHR(hr);。
26. 处理回调（如果需要）：.NET 8+ 首选 UnmanagedCallersOnly，避免 delegate 和 GC 生命周期风险；方法必须 static、不能向原生代码抛异常、只能使用 blittable 参数类型；声明 [LibraryImport("mylib")] private static unsafe partial void SetLogCallback(delegate* unmanaged<int, IntPtr, void> cb); 并用 unsafe { SetLogCallback(&LogCallback); }。
27. 回调回退方案（更早 TFM 或需要实例状态）：用带 rooting 的 delegate；[UnmanagedFunctionPointer(CallingConvention.Cdecl)] 仅在 Windows x86 需要；用 private static LogCallbackDelegate? s_logCallback; 防止 delegate 被垃圾回收；如果原生代码存储函数指针，delegate 必须在其整个生命周期保持 rooted，delegate 被回收会导致崩溃。
28. 短生命周期回调使用 GC.KeepAlive：当用 Marshal.GetFunctionPointerForDelegate 把 delegate 转成函数指针时，GC 不跟踪指针与 delegate 的关系；在原生调用完成后调用 GC.KeepAlive(callback) 防止提前回收。
29. 跨平台加载库：复杂场景用 NativeLibrary.SetDllImportResolver，简单场景用条件编译；C long/unsigned long 用 CLong/CULong；注意 CLong/CULong 搭配 LibraryImport 需要 [assembly: DisableRuntimeMarshalling]。
30. 最简单场景使用平台命名约定：默认命名约定在搜索原生库时添加对应前缀和扩展名，结果是 Windows 上 mylib.dll、Linux 上 libmylib.so、macOS 上 libmylib.dylib；可写 private const string LibName = "mylib";。
31. 简单条件编译：WINDOWS、LINUX、MACOS 只在面向 OS 特定 TFM（例如 net8.0-windows）时预定义，面向可移植 TFM（例如 net8.0）时没有定义，此时改用运行时 resolver；条件编译中分别设置 LibName 为 mylib.dll、libmylib.so、libmylib.dylib。
32. 复杂运行时 resolver：用 NativeLibrary.SetDllImportResolver(typeof(MyLib).Assembly, (name, assembly, searchPath) => { if (name != "mylib") return IntPtr.Zero; string libName = OperatingSystem.IsWindows() ? "mylib.dll" : OperatingSystem.IsMacOS() ? "libmylib.dylib" : "libmylib.so"; NativeLibrary.TryLoad(libName, assembly, searchPath, out var handle); return handle; });；面向 netstandard2.0 或其他没有 OperatingSystem.IsXXX 的框架时，用 RuntimeInformation.IsOSPlatform(OSPlatform.XXX)。
33. 从 DllImport 迁移到 LibraryImport：面向 .NET 7+ 时迁移可获得 AOT 兼容和 trimming 安全；给包含类加 partial，并把方法改为 static partial；把 [DllImport] 替换为 [LibraryImport]；把 CharSet 替换为 StringMarshalling；把 SetLastError = true 替换为 SetLastPInvokeError = true；除非面向 Windows x86，否则移除 CallingConvention；构建并修复 SYSLIB1054–SYSLIB1057 分析器警告。
34. 启用 interop 分析器：在 PropertyGroup 中设置 <EnableTrimAnalyzer>true</EnableTrimAnalyzer> 和 <EnableAotAnalyzer>true</EnableAotAnalyzer>。
35. Win32 API 工具：优先使用 Microsoft.Windows.CsWin32 而不是手写签名，它从元数据 source-generate 正确声明；用 dotnet add package Microsoft.Windows.CsWin32 添加包，并在 NativeMethods.txt 列出需要的 API。
36. WinRT API 工具：用 Microsoft.Windows.CsWinRT 从 .winmd 文件生成 .NET projections。
37. Objective-C API 工具：绑定 macOS/iOS 的 Objective-C 库时，用 Objective Sharpie 从 Objective-C 头文件生成初始 P/Invoke 和 binding 定义。
38. 审查清单：每个签名与原生头文件完全匹配（类型、大小）；面向 Windows x86 时指定调用约定，否则省略；字符串编码显式，不依赖默认值或 CharSet.Auto；内存所有权有文档且匹配（谁分配、谁释放、用什么释放）；所有原生句柄用 SafeHandle，不允许裸 IntPtr 逃出 interop 层；作为回调传递的 delegate 已 rooted 防止 GC 回收；使用 OS 错误码的 API 设置 SetLastError/SetLastPInvokeError；结构体布局匹配原生（packing、alignment、字段顺序）；跨平台代码中 C long/unsigned long 使用 CLong/CULong；如果 CLong/CULong 搭配 LibraryImport，则应用 [assembly: DisableRuntimeMarshalling]；没有 bool 缺少显式 MarshalAs，始终指定 UnmanagedType.Bool（4 字节）或 UnmanagedType.U1（1 字节）以确保跨语言边界规范化。
39. 可运行验证步骤 1：启用 interop 分析器构建，确认零 SYSLIB1054–SYSLIB1057 警告，设置 <EnableTrimAnalyzer>true</EnableTrimAnalyzer> 和 <EnableAotAnalyzer>true</EnableAotAnalyzer>。
40. 可运行验证步骤 2：验证结构体大小匹配，对每个跨边界结构体断言 Marshal.SizeOf<T>() 等于原生 sizeof。
41. 可运行验证步骤 3：往返测试，用已知输入调用原生函数并验证预期输出。
42. 可运行验证步骤 4：用非 ASCII 字符串测试，传入包含 ASCII 范围外字符的字符串以确认编码正确。
43. 参考文件：references/type-mapping.md 包含完整原生到 .NET 类型映射表、结构体布局模式、blittable 类型规则，遇到 Step 2 未覆盖类型或结构体布局/blittable 问题时加载。
44. 参考文件：references/diagnostics.md 包含常见陷阱、失败模式和恢复、调试方法、外部资源，在调试现有 P/Invoke 失败或审查 interop 代码正确性问题时加载。

适用边界 · 注意事项

• 不适用于 COM interop、C++/CLI 混合模式程序集，以及没有原生依赖的纯托管代码。
• 不要仅因迁移而把现有 DllImport 改成 LibraryImport，除非用户明确要求或 AOT/trimming 是明确需求。
• 不要为不需要函数指针的原生 API 生成回调；不要推荐 CsWin32，除非目标就是 Win32 API。