TL;DR
建议使用 ClangSharpPInvokeGenerator 生成 P/Invoke 绑定代码。在需要人工介入的情况下可以参照本文前半部分介绍绑定技巧的部分进行修改。生成绑定后仍然建议对其二次封装使之更符合 .NET 的使用习惯。
展示
我在 OptimeGBA.io 中手写了 libvpx 的绑定，而用 ClangSharpPInvokeGenerator 生成了 libopenh264 的绑定，供各位对比绑定生成的质量。此外，这两个库的二次封装也可作为案例参考如何将 .NET 与非托管资源的互操作体验更加原生。
运行效果可以在此体验：https://aws.martincl2.me/OptimeGBA.io/。部署的版本使用了 h264 编码。
P/Invoke 是什么
P/Invoke 是 .NET 中与二进制代码库互操作的机制。得益于 .NET 优秀的底层操作能力，P/Invoke 可以在没有额外非托管代码包装的情况下直接与二进制接口互操作。相较 Java 的 JNI 或是 Node.js 的 V8 binding 之下，P/Invoke 可以省去一部分 native code 编译链的耦合，而更重要的是 P/Invoke 的绑定不受 .NET 大版本更新的影响，即一次绑定，所有大版本兼容。
P/Invoke 举例来说， getpid 的 C 接口可以被直接在 C# 中引用：
|
1 2 |
// C 接口 pid_t getpid(void); |
|
1 2 |
// C# 绑定 static extern int getpid(); |
当然， getpid 是极为简单的例子。常见的互操作中需要使用更为复杂的结构体、指针、生命周期管理，同时还要保证 C# 侧调用的时候能尽可能贴合 C# 的代码风格。此文就以我在 OptimeGBA.io 中的经验为基础，简单分享一下如何迅速而优雅地为一个二进制库实现 P/Invoke 绑定。
生成 P/Invoke 绑定
简单结构体
C# 的结构体声明与内存结构（Layout）几乎是完美兼容 C 的。甚至对于一个简单的结构体而言，只需要简单的复制粘贴就能完成绑定。例如以下的 C 结构体便可以直接翻译为 C# 的结构体：
|
1 2 3 4 5 6 7 |
// C struct MyStruct { int a; unsigned char b; double c; void* d; }; |
|
1 2 3 4 5 6 7 8 |
// C# unsafe struct MyStruct { int a; byte b; double c; void* d; } |
其中字段的顺序、大小，甚至是内存对齐（ byte b 后会留空三字节），C# 都与 C 的行为一致。
翻译 typedef – 预设别名
C 接口中大量使用了 typedef，甚至可以说是无可避免地会使用 typedef，因为在实际操作上 C 依赖各种编译器预设的 typedef 来实现跨平台源代码兼容，因而 C 标准库中的函数签名就大量使用了 typedef。例如在上文 getpid 的例子中，该函数的返回值是 pid_t，而如果在 amd64 的目标平台编译器下顺着标准库的头文件查找并且把 typedef 的声明全都实体化，最终就会发现 pid_t 在本平台的定义实际上是 int。
在 C# 中显然并没有诸如 pid_t 的类型别名，因此在写 P/Invoke binding 的时候需要逐个找到这些别名在本平台的实际定义。通常这在 IDE 环境下跳转几次就能找到了。如果对结果不确定可以用 sizeof 验算一下字段长度——毕竟只要字段长度对了，最不济也就一个字段数据不对，而如果长度错了那后面的字段偏移量就全部完蛋了。
此外，虽说如今主流平台的这些 *_t 类型的实际类型基本上是一致的，还是要小心跨平台的时候会有平台差异。
翻译 typedef – 自定义别名
一些情况下 typedef 可以为某个类型设置一个友好而可读的别名。例如说在 C API 中非常常见的一种做法是在结构体或参数里放一个 void* 存放一些内部实现相关的数据。调用方并不需要知道这个指针怎么来的以及存了什么，而只需要保证指针传递到了就行。而此时设计函数签名的时候就可以通过 typedef 给这个 void* 设置别名以便跟别的指针做出区隔：
|
1 2 3 4 5 |
typedef void* EncoderContext; EncoderContext create_encoder(...); void encode(EncoderContext ctx, ...); |
虽说 C 编译器不会对设置了别名的 void* 做出任何区隔，换言之随便传一个指针进去都能通过编译（然后运行的时候爆炸），但在函数中使用了别名后作为调用方可以更直观地理解应该具体传什么指针进去而不是完全依赖阅读文档。
而当翻译这段 API 到 C# 的时候，固然可以直接使用 void* 作为变量类型，但也可以通过一个但字段的结构体包装这个指针以达到类似 typedef 的效果，甚至可以通过这种方法在编译时就能完成指针类型的检查：
|
1 2 3 4 5 6 7 8 |
unsafe struct EncoderContext { void* pointer; } static class EncoderApi { static extern EncoderContext create_encoder(...); static extern void encode(EncoderContext ctx, ...); } |
由于这个包装的结构体的数据长度和一个指针完全相同，通过包装结构体定义的函数签名与使用指针在效果上是同样的。
Enum
C 的枚举类型本质上是 int——「正巧」C# 也是。因此如果 C header 中有 enum 的定义，或是函数签名中有用作 flag 的 int，都可以用 C# 替换。例如：
|
1 2 3 4 5 6 7 8 9 10 |
// C typedef enum { A, B, C } MyEnum; // 在参数传递 enum 的以下两种写法都会见到 void MyFunc1(MyEnum a); void MyFunc2(int a); |
|
1 2 3 4 5 6 7 8 9 10 11 |
// C# enum MyEnum { A, B, C } // enum 与 int 类型的参数都可以直接传 C# enum static extern void MyFunc1(MyEnum a); static extern void MyFunc2(MyEnum a); |
* 与其说是「正巧」应该说是 C# 一步到位直接把 enum 的语法与行为定义为与 C 一致。
如果万一遇到不一致的情况，或是需要手动调整字段的内存布局，则可以使用 StructLayoyt 与 FieldOffset 作细致的调整。具体可以参照下文介绍 union 的部分。
Fixed buffer
在 C 标准中，结构体上是可以定义固定长度的数组的。例如：
|
1 2 3 4 |
// C struct MyStruct { int plane[4]; }; |
对于不熟悉 C 的读者请注意：这不同于定义一个指针字段并赋值一个数组指针（如 int* plane)，这个数组字段的实际数据是存在于结构体内部的，因而在使用的时候编译器只需简单地将结构体的指针偏移几个字段就能拿到这个定长数组的指针。
而在 C# 中，简单情况下可以用 fixed buffer 声明这种数组：
|
1 2 3 4 5 |
// C# struct MyStruct { fixed int plane[4]; } |
但是 C# 目前只支持 primitive unmanaged type 用作 fixed buffer，也就是 int、 ulong 等类型。换言之，结构体或指针之类的数据类型就不能这样定义了。这种情况下就必须手动展开了：
|
1 2 3 4 5 6 7 8 9 10 11 12 |
// C# struct MySruct { // 原本 plane 会是个指针类型。需要使用原定义的话就要对第一个元素取引用：&plane1 int plane1; int plane2; int plane3; int plane4; // 可以进一步包装成 Span<T> 以获得更好的 C# API 体验 Span<int> Plane => MemoryMarshal.CreateSpan(ref plane1, 4); } |
Union
Union 是一种 C 中非常常用的结构体布局。具体而言，union 允许将多个不同的数据段存储在同一段内存中。例如：
|
1 2 3 4 5 6 7 8 9 10 11 |
struct Frame { FrameType type; union FrameData { KeyFrame keyFrame; InterFrame interFrame; } data; } struct Frame f; // f.data.keyFrame 与 f.data.interFrame 实际上指向同一段内存 |
在 C# 中可以通过手动指定字段偏移量的方式定义一个 union 结构体。结构体上的 StructLayoyt 属性告诉编译器一个结构体需要手动设置字段偏移量，而字段上的 FieldOffset 属性则设置了具体字段偏移量的数值。对于 union 而言，只需要将 FieldOffset 全部设置为 0 即可。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
[StructLayoyt(LayoutKind.Explicit)] struct Frame { FrameType type; struct FrameData { [FieldOffset(0)] KeyFrame keyFrame; [FieldOffset(0)] KeyFrame interFrame; } FrameData data; } Frame f; // f.data.keyFrame 与 f.data.interFrame 也指向同一段内存，并且 Frame 结构体的整体内存布局与 C 一致 |
自动生成绑定
虽说以上讲了这么多使用场景、解决方案与技巧，在了解与攻破了这些场景以后写绑定这件事本身其实是个体力活。尤其是 C header 很可能散落各地，编排顺序也并无逻辑，而逐个翻译 header 中的每一个定义既吃力又容易出错。那么有没有方便又可靠的工具可以一键无脑生成绑定代码的呢？有！那便是 ClangSharp 的 PInvokeGenerator。
Clang 是 llvm 工具链中处理 C 与 C++ 的前端。编译器里的前端大致上指的是处理分析源代码的部分——将源代码 parse 成抽象语法树（AST）、分析符号、处理宏，等等。而 ClangSharp 是一个 Clang 的 C# 绑定，换言之，ClangSharp 是一个在 .NET 中处理 C/C++ 源代码的工具。为何要花篇幅介绍 Clang？因为 Clang 普遍认为是最模组化、功能齐全，而业界又广泛采用的 C/C++ 前端。也就是说，如果采用 ClangSharp 分析 C/C++ 源码，将会得到与业界主流编译器 clang 完全一致的结果。这也就意味着 ClangSharp 可以为自动生成 P/Invoke 绑定提供非常可靠的信息源。顺带一提，这与 C# 编译器 Roslyn 的设计目的之一相同：编译器一次实现，多处应用，包括编译本身、静态分析、Language Server （IDE 集成）等等，以保证结果的一致性。
* 注：ClangSharp 本身就是通过 ClangSharpPInvokeGenerator 自己生成的绑定代码。
安装 ClangSharpPInvokeGenerator：
|
1 |
dotnet tool install --global ClangSharpPInvokeGenerator |
生成绑定：
|
1 |
ClangSharpPInvokeGenerator --file <header-file> --namespace <dotnet-namespace> --output <output-dir> |
然后将生成的绑定代码复制到项目的源码即可。
* 注意有一些库同时提供了 C 与 C++ 的头文件。这种情况下通常直接为 C++ 的头文件生成绑定会让生成的代码更干净。
通常来说生成的绑定无需修改已经足够可读了。不对生成的代码作任何修改可以保证今后再次生成头文件时可以无缝升级。当然我也遇到了一些不理想的生成，例如有一些库将 enum 通过 #define 定义为了常数，我会手动将其改成 enum。
将绑定封装为 .NET 库
绑定其实只完成了一半的工作。为了让非托管库的调用更符合 .NET 的使用习惯，同时也保证调用安全、减少 unsafe 的使用，我们仍然需要对绑定代码作二次封装。毕竟都用 .NET 了，总不能让调用方仍然手动操作指针吧。
内存管理——IDisposable
.NET 拥有 GC，而非托管代码则并没有。因而使用 P/Invoke 的时候要格外注意来自非托管对象的生命周期。
以 libvpx（已简化）为例，一个典型的 C 库需要这样管理生命周期：
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 |
// 栈上分配： int main() { // 分配 vpx_codec_ctx_t codec; vpx_codec_enc_init(&codec); // 使用 codec... // 销毁 vpx_codec_destroy(&codec); } // 堆上分配： int main() { // 分配 vpx_codec_ctx_t* codec = malloc(sizeof(vpx_codec_ctx_t)); vpx_codec_enc_init(codec); // 使用 codec... // 销毁 vpx_codec_destroy(codec); free(codec); } |
对于手动管理生命周期的运行时而言，分配与销毁必须成对出现，包括出现异常的情况下，不然轻则内存泄漏，重则整个进程原地爆炸。
.NET 标准库中的 IDisposable 则提供了一个统一且设计良好的范式——调用方既可以通过 using 语句实现类似 RAII 的作用域级自动释放，也可以将非托管资源的生命周期与托管资源的生命周期（GC）挂钩自动释放。
举例而言，上述 libvpx 的例子使用 IDisposable 封装：
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 |
public unsafe class VpxCodec : IDisposable { private readonly vpx_codec_ctx_t* _codec; public VpxCodec() { // 堆上分配并初始化 _codec = (vpx_codec_ctx_t*)Marshal.AllocHGlobal(sizeof(vpx_codec_ctx_t)).ToPointer(); vpx_codec_enc_init(_codec); } // IDispoable 的模板代码大多数 IDE 都可以自动生成。按照功能填入实现即可。 // IDispoable 模板的一部分：确保不会重复释放非托管资源 private bool disposedValue = false; // IDispoable 模板的一部分：如果没有手动释放（例如通过 using），则在 GC 销毁该托管对象的时候一并销毁非托管对象 ~VpxCodec() { // Do not change this code. Put cleanup code in 'Dispose(bool disposing)' method Dispose(disposing: false); } // IDisposable 模板的一部分：using 语句会在代码离开作用域的时候自动调用 Dispose() 方法 public void Dispose() { // Do not change this code. Put cleanup code in 'Dispose(bool disposing)' method Dispose(disposing: true); GC.SuppressFinalize(this); } // IDisposable 模板的一部分： private void Dispose(bool disposing) { if (!disposedValue) { if (disposing) { // dispose managed state (managed objects) } // free unmanaged resources (unmanaged objects) and override finalizer // 销毁对象与其堆上分配 vpx_codec_destroy(_codec); Marshal.FreeHGlobal(new IntPtr(_config)); disposedValue = true; } } } |
IDisposable 的模板看着很庞大，但其实已经考虑好了各种边角情况，因此最好还是按照模板实现。
内存操作——Span<T>
.NET 一类的托管语言的一大卖点在于全自动的边界检查。在 .NET 的数组中任何越界的访问都会触发异常，而不是造成越界访问的漏洞。然而在非托管资源上边界检查往往要手动实现。在 .NET 中，我们可以借助 Span<T> 对非托管内存块进行封装。
例如说一个典型的 C 结构会这样暴露一段内存：
|
1 2 3 4 |
struct my_struct { int data*; size_t length; } |
使用 Span<T> 封装后：
|
1 2 3 4 5 6 |
public class MyStruct { private my_struct* raw; public Data => new Span(raw->data, raw->length); } |
迭代器——IEnumerable<T>
迭代器是非常常见的一种范式，但在非托管代码中的实现不尽相同。既然要封装成 .NET 库，就要让迭代器的使用体验更接近原生的 .NET 代码。
例如 libvpx 中，要获得编码后的帧数据需要多姿迭代，其 C 接口需要这样使用迭代器（代码已简化）：
|
1 2 3 4 5 6 7 8 9 |
void encode_frame(vpx_codec_ctx_t *codec, vpx_image_t *img) { vpx_codec_iter_t iter = NULL; const vpx_codec_cx_pkt_t *pkt = NULL; vpx_codec_encode(codec, img); while ((pkt = vpx_codec_get_cx_data(codec, &iter)) != NULL) { // 处理帧数据 pkt } } |
而 .NET 中的标准迭代器是 IEnumberable<T>，也就是 C# 中的 foreach 语句所使用的接口。因此这个 libvpx 的例子理想情况下在 C# 中的调用应该大致上是这样的：
|
1 2 3 4 5 6 7 |
void EncodeFrame(VpxCodec codec, VpxImage img) { foreach (VpxPacket pkt in codec.Encode(img)) { // 处理帧数据 pkt } } |
为了达到这个效果， IEnumerable<VpxPacket> 的实现可以写作：
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
public class VpcEncoder { private vpx_codec_ctx_t* Pointer; public IEnumerable<VpxPacket> Encode(VpxImage img) { vpx_codec_encode(this.Pointer, img.Pointer); vpx_codec_iter_t iter = default; vpx_codec_cx_pkt_t *pkt = null; while ((pkt = vpx_codec_get_cx_data(codec, &iter)) != null) { yield return new VpxPacket(pkt); } } } |
当然，如果为了追求零分配，也可以手写 struct Enumerable 与 struct Enumerator，只不过会长得多：
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 |
public class VpcEncoder { private vpx_codec_ctx_t* Pointer; public VpxPacketEnumerable Encode(VpxImage img) { vpx_codec_encode(this.Pointer, img.Pointer); return new VpxPacketEnumerable(this.Pointer); } } public unsafe struct VpxPaceteEnumerable : IEnumerable<VpxPacket> { public struct Enumerator : IEnumerator<VpxPacket> { public VpxPacket Current { get; private set; } object IEnumerator.Current => Current; private readonly vpx_codec_ctx_t* _codec; private readonly vpx_codec_iter_t _iter; public Enumerator(vpx_codec_ctx_t* codec) { _codec = codec; _iter = default; Current = default; } public bool MoveNext() { vpx_codec_cx_pkt_t* packet; fixed (vpx_codec_iter_t* iterRef = &_iter) { packet = vpx_codec_get_cx_data(_codec, iterRef); } Current = new VpxPacket(packet); return packet != null; } public void Dispose() { } public void Reset() => throw new NotSupportedException(); } private readonly vpx_codec_ctx_t* _codec; public VpxPacketEnumerable(vpx_codec_ctx_t* codec) { _codec = codec; } IEnumerator IEnumerable.GetEnumerator() => GetEnumerator(); IEnumerator<VpxPacket> IEnumerable<VpxPacket>.GetEnumerator() => GetEnumerator(); public Enumerator GetEnumerator() { return new Enumerator(_codec); } } |
异步回调——Task<T>
在一些涉及到 IO 的非托管库中可能会提供基于回调的异步调用的接口，例如：
|
1 |
void read(void (*callback)(int)); |
这种情况下可以用 TaskCompletionSource<T> 来将回调封装成异步调用（ async/ await）：
|
1 2 3 4 5 6 7 8 9 |
Task<int> Read() { TaskCompletionSource<int> tcs = new TaskCompletionSource<int>(); // 这里其实要对 Lambda 作处理，防止 GC 在回调前介入。在此篇幅所限简略处理。 read(result => tcs.SetResult(result)); return tcs.Task; } |
此外，如果该非托管库还支持 Cancellation Token，那一定要做好对接。
由于 OptimeGBA.io 项目中并未涉及到非托管回调，我手头并没有足够的案例，也因此暂无法展开更多细节。有机会的话再开坑补充。
va_list——建议手动添加签名
C 标准是支持可变参数的函数签名的。尽管 P/Invoke 也可以通过 __arglist 兼容此类函数签名，但其适用范围非常受限（例如很难多级传递），文档也非常模糊。个人建议不如根据实际调用情况多写几个函数签名。
|
1 |
void test(const char* fmt, ...); |
|
1 2 3 4 5 6 7 8 |
// 不建议 static extern void test(string fmt, __arglist); // 建议 static extern void test(string fmt); static extern void test(string fmt, int arg1); static extern void test(string fmt, int arg1, int arg2); static extern void test(string fmt, int arg1, int arg2, int arg3); |
结语
.NET 通过 P/Invoke 对非托管库的调用由于 ClangSharp 的出现在工程上让本就颇为强大的 P/Invoke 更具可行性与可维护性。但是要让 .NET 与非托管资源之间的互操作更贴近原生体验还是需要话心思作二次封装。在此也再次欢迎读者阅读 OptimeGBA.io 项目中的 libvpx（手写绑定）与 libopenh264（ClangSharp 生成绑定）交互代码作为参考案例。
近期评论