DeepSeek总结的用 C# 构建 DuckDB 插件说明

原文地址https://duckdb.org/2026/03/20/duckdb-extensionkit-csharpDuckDB.ExtensionKit用 C# 构建 DuckDB 扩展Giorgi Dalakishvili2026-03-20 · 9分钟阅读TL;DRDuckDB.ExtensionKit 将 DuckDB 扩展开发带入了 .NET 生态系统。它基于 DuckDB 稳定的 C 扩展 API并利用 .NET Native AOT 编译让 C# 开发者能够定义标量函数和表函数并将其打包为原生的 DuckDB 扩展。引言DuckDB 拥有灵活的扩展机制允许在运行时动态加载扩展。这使得扩展 DuckDB 的主要功能集变得容易而无需将所有功能都添加到主二进制文件中。扩展可以增加对新文件格式的支持、引入自定义类型或提供新的标量和表函数。DuckDB 的很大一部分功能实际上就是通过这种扩展机制以核心扩展的形式实现的这些核心扩展由 DuckDB 团队与引擎本身一同开发。例如DuckDB 通过json扩展读写 JSON 文件并通过postgres扩展与 PostgreSQL 集成。DuckDB 还有一个蓬勃发展的社区扩展生态系统即由社区成员维护的第三方扩展涵盖了广泛的用例和集成。例如您可以通过crypto社区扩展来使用额外的加密功能。当前如何构建扩展如今开发者可以使用与核心扩展相同的 C API 来开发扩展。创建扩展的模板可以在extension-template仓库中找到。虽然功能强大但 C 扩展 API 与 DuckDB 的内部 API 紧密耦合因此它在不同 DuckDB 版本之间可能并且经常会发生变化。此外使用它需要构建整个 DuckDB 引擎并且其文档不如 C API 那么完整。为了解决这些问题DuckDB 还提供了一个实验性的 C/C 扩展模板该模板与 DuckDB 的 C 扩展 API 链接。这个 API 为开发扩展提供了一个稳定、向后兼容的接口旨在让扩展能够在不同的 DuckDB 版本上工作。由于它是基于 C 的 API因此也可以从 Rust 等其他编程语言中使用。即使有了 C API编写扩展仍然意味着要在底层工作进行手动内存管理并编写大量样板代码。虽然 C API 解决了稳定性和兼容性问题但它并没有为更高级的生态系统解决开发体验问题。这就是 DuckDB.ExtensionKit 的用武之地它旨在让 .NET 生态系统中的开发者更容易进行扩展开发。通过构建在 DuckDB C 扩展 API 之上并使用 .NET Native AOT 编译扩展DuckDB.ExtensionKit 提供了两全其美的方案既能像任何其他扩展一样集成的原生 DuckDB 扩展又能享受 C# 和 .NET 的生产力及丰富的库生态系统。DuckDB.ExtensionKitDuckDB.ExtensionKit 提供了一套 C# API 和构建工具用于实现 DuckDB 扩展。它将底层的 DuckDB C 扩展 API 暴露为 C# 方法并提供了类型安全的、更高级的 API 来定义标量函数和表函数同时仍然生成原生的 DuckDB 扩展。该工具包还包含一个源代码生成器自动生成所需的样板代码包括本地入口点和 API 初始化。使用 DuckDB.ExtensionKit构建扩展非常接近于构建一个常规的 C# 库。扩展作者创建一个引用 ExtensionKit 运行时的 C# 项目并使用提供的、暴露 DuckDB 概念的类型安全 API 来实现函数。在构建时源代码生成器会发出所需的样板代码包括本地入口点和扩展初始化。然后该项目使用 .NET Native AOT 进行编译生成一个原生的 DuckDB 扩展二进制文件该文件可以像任何其他扩展一样被 DuckDB 加载和使用而无需 .NET 运行时。为了展示这个过程的具体示例下面的代码片段展示了一个使用 DuckDB.ExtensionKit 实现的小型 DuckDB 扩展该扩展同时暴露了一个标量函数和一个用于处理 JWT 的表函数。在高层面上使用 DuckDB.ExtensionKit 编写扩展涉及定义一个代表扩展的 C# 类型并显式注册函数。在下面的示例中这是通过创建一个带有[DuckDBExtension]特性的分部类并实现RegisterFunctions方法来完成的。该实现使用了System.IdentityModel.Tokens.JwtNuGet 包说明了扩展如何轻松利用现有的 .NET 库。我们将添加两个函数一个用于从 JWT 中提取单个声明的标量函数以及一个用于提取多个声明的表函数。publicstaticpartialclassJwtExtension{privatestaticvoidRegisterFunctions(DuckDBConnectionconnection){connection.RegisterScalarFunctionstring,string,string?(extract_claim_from_jwt,ExtractClaimFromJwt);connection.RegisterTableFunction(extract_claims_from_jwt,(stringjwt)ExtractClaimsFromJwt(jwt),cnew{claim_namec.Key,claim_valuec.Value});}privatestaticstring?ExtractClaimFromJwt(stringjwt,stringclaim){varjwtHandlernewJwtSecurityTokenHandler();vartokenjwtHandler.ReadJwtToken(jwt);returntoken.Claims.FirstOrDefault(cc.Typeclaim)?.Value;}privatestaticDictionarystring,stringExtractClaimsFromJwt(stringjwt){varjwtHandlernewJwtSecurityTokenHandler();vartokenjwtHandler.ReadJwtToken(jwt);returntoken.Claims.ToDictionary(cc.Type,cc.Value);}}仅仅 25 行代码我们就构建了一个向 DuckDB 添加extract_claim_from_jwt和extract_claims_from_jwt函数的扩展。我们可以像调用任何其他函数一样调用这些函数。例如要从声明中提取name字段我们可以运行SELECTextract_claim_from_jwt(eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6ImExZmIyY2NjN2FiMjBiMDYyNzJmNGUxMjIwZDEwZmZlIn0.eyJpc3MiOiJodHRwczovL2lkcC5sb2NhbCIsImF1ZCI6Im15X2NsaWVudF9hcHAiLCJuYW1lIjoiR2lvcmdpIERhbGFraXNodmlsaSIsInN1YiI6IjViZTg2MzU5MDczYzQzNGJhZDJkYTM5MzIyMjJkYWJlIiwiYWRtaW4iOnRydWUsImV4cCI6MTc2NjU5MTI2NywiaWF0IjoxNzY2NTkwOTY3fQ.N7h2xc4rgS4oPo8IO9wyG1lnr2wqTUC80YudWTXp7rXmU2JdsUiweKmuYVVbygdJAR4PJmbQtak4_VuZg2fZFILVpzDyLvGITfUW_18XuDQ_SIm3VlfAuHOVHfruuvvSAfjUkTW2Jlrv3ihFYgusV58vjhcVFHssOGMEbtMNo10Jf62dczVVGNZXh_OOLS0nTLffhY94sZddqQIE56W8xhLK5YMO4gO8voMzhUwDwucnVvyNfui38MPDNdTSKjn3Ab0hG8jzOVhbYSCHf0eQsbxPzGtXUCJobScWDb78IphFWec6W4ugIYp5CMh3C_noQi94NYjQg2P-AJ5FLCKzKA,name);这将返回Giorgi Dalakishvili。让我们测试一下表函数SELECT*FROMextract_claims_from_jwt(eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6ImExZmIyY2NjN2FiMjBiMDYyNzJmNGUxMjIwZDEwZmZlIn0.eyJpc3MiOiJodHRwczovL2lkcC5sb2NhbCIsImF1ZCI6Im15X2NsaWVudF9hcHAiLCJuYW1lIjoiR2lvcmdpIERhbGFraXNodmlsaSIsInN1YiI6IjViZTg2MzU5MDczYzQzNGJhZDJkYTM5MzIyMjJkYWJlIiwiYWRtaW4iOnRydWUsImV4cCI6MTc2NjU5MTI2NywiaWF0IjoxNzY2NTkwOTY3fQ.N7h2xc4rgS4oPo8IO9wyG1lnr2wqTUC80YudWTXp7rXmU2JdsUiweKmuYVVbygdJAR4PJmbQtak4_VuZg2fZFILVpzDyLvGITfUW_18XuDQ_SIm3VlfAuHOVHfruuvvSAfjUkTW2Jlrv3ihFYgusV58vjhcVFHssOGMEbtMNo10Jf62dczVVGNZXh_OOLS0nTLffhY94sZddqQIE56W8xhLK5YMO4gO8voMzhUwDwucnVvyNfui38MPDNdTSKjn3Ab0hG8jzOVhbYSCHf0eQsbxPzGtXUCJobScWDb78IphFWec6W4ugIYp5CMh3C_noQi94NYjQg2P-AJ5FLCKzKA);这将返回claim_nameclaim_valueisshttps://idp.localaudmy_client_appnameGiorgi Dalakishvilisub5be86359073c434bad2da3932222dabeadmintrueexp1766591267iat1766590967DuckDB.ExtensionKit 工作原理DuckDB.ExtensionKit 依赖于几个现代 C# 语言和运行时特性以高效地将 DuckDB 的 C 扩展 API 桥接到托管代码。这些特性使得在 C# 中构建原生扩展成为可能而无需在加载时引入托管运行时依赖。函数指针DuckDB 的 C 扩展 API 被暴露为一个带版本号的函数表一个大的结构体duckdb_ext_api_v1其字段是 C 函数指针例如duckdb_openduckdb_register_scalar_functionduckdb_vector_get_data等等。DuckDB.ExtensionKit 在 C# 中镜像了这一机制。它定义了该结构体的 C# 表示 (DuckDBExtApiV1)其中每个字段被声明为一个 C# 函数指针 (delegate* unmanaged[Cdecl]...)。这直接映射了 C ABI调用 DuckDB 变成了一个通过函数指针对字段的简单间接调用而不是带有运行时封送处理的委托调用。入口点DuckDB 扩展需要暴露一个遵循 C 调用约定的入口点函数应从二进制文件中导出的入口点名称是扩展名加上_init_c_api。这样DuckDB 在加载扩展时就能找到它。在 C 扩展模板中这是通过宏来处理的这些宏生成导出的函数和周围的样板代码。DuckDB.ExtensionKit 遵循相同的模型但从 C# 而不是 C 宏生成样板代码。源代码生成器会发出一个与原生兼容的入口点该入口点检索 API 表通过访问对象并执行所需的初始化就像 C 模板所做的那样。生成的方法带有[UnmanagedCallersOnly(EntryPoint ...)]特性这指示 .NET 工具链导出一个具有该名称的真实原生符号并使其可以从 C 调用。通过 .NET Native AOT这成为生成二进制文件中一个实际导出的函数——允许 DuckDB 像加载 C 实现一样加载并调用该扩展。Native AOT最后Native AOT 是这种方法对 DuckDB 扩展变得实用的关键。一旦扩展代码和生成的源代码被编译该项目就会使用 .NET Native AOT 发布。此步骤生成一个原生二进制文件在加载时没有对托管运行时的依赖。生成的结果是一个原生的 DuckDB 扩展可以像用 C 或 C 编写的扩展一样被加载和执行。从 DuckDB 的角度来看用 DuckDB.ExtensionKit 构建的扩展和用传统原生语言实现的扩展之间没有区别。当前状态与限制DuckDB.ExtensionKit 与 C 扩展模板一样目前是实验性的。API 仍在发展中并非 DuckDB 支持的所有扩展功能都已暴露出来。该工具包依赖于 .NET Native AOT这意味着扩展需要针对特定的目标平台例如linux-x64osx-arm64或win-x64构建。与其他原生扩展一样二进制文件是平台特定的需要相应地进行构建。用 C# 构建自己的扩展DuckDB.ExtensionKit 作为开源项目在 GitHub 上提供采用 MIT 许可证。该项目包含示例扩展演示了如何在 C# 中定义和构建 DuckDB 扩展。该仓库包含一个基于 JWT 的示例扩展展示了标量函数和表函数以及使用 .NET Native AOT 的完整构建和发布流程。欢迎通过 GitHub issues 提供反馈、报告错误和贡献代码。结语DuckDB 的扩展机制已被证明是一个灵活的基石可以在不复杂化核心引擎的情况下扩展系统。DuckDB.ExtensionKit 探索了如何通过利用 .NET 生态系统使这一机制能够被更广泛的受众所使用同时仍然生成可直接与 DuckDB 集成的原生扩展。尽管 C# 通常被视为高级语言但这个项目证明了在需要时它也可以用来实现底层的、ABI 兼容的组件。通过结合现代 C# 特性和 DuckDB 现有的扩展接口我们可以在高级语言中编写扩展而无需放弃对原生边界的控制。