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

原文地址：https://duckdb.org/2026/03/20/duckdb-extensionkit-csharp

DuckDB.ExtensionKit：用 C# 构建 DuckDB 扩展

Giorgi Dalakishvili

2026-03-20 · 9分钟阅读

TL;DR： DuckDB.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.ExtensionKit

DuckDB.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.Jwt NuGet 包，说明了扩展如何轻松利用现有的 .NET 库。

我们将添加两个函数：一个用于从 JWT 中提取单个声明的标量函数，以及一个用于提取多个声明的表函数。

csharp 复制代码

public static partial class JwtExtension
{
  private static void RegisterFunctions(DuckDBConnection connection)
  {
    connection.RegisterScalarFunction<string, string, string?>("extract_claim_from_jwt", ExtractClaimFromJwt);

    connection.RegisterTableFunction("extract_claims_from_jwt", (string jwt) => ExtractClaimsFromJwt(jwt),
                                     c => new { claim_name = c.Key, claim_value = c.Value });
  }

  private static string? ExtractClaimFromJwt(string jwt, string claim)
  {
    var jwtHandler = new JwtSecurityTokenHandler();
    var token = jwtHandler.ReadJwtToken(jwt);
    return token.Claims.FirstOrDefault(c => c.Type == claim)?.Value;
  }

  private static Dictionary<string, string> ExtractClaimsFromJwt(string jwt)
  {
    var jwtHandler = new JwtSecurityTokenHandler();
    var token = jwtHandler.ReadJwtToken(jwt);
    return token.Claims.ToDictionary(c => c.Type, c => c.Value);
  }
}

仅仅 25 行代码，我们就构建了一个向 DuckDB 添加 extract_claim_from_jwt 和 extract_claims_from_jwt 函数的扩展。我们可以像调用任何其他函数一样调用这些函数。例如，要从声明中提取 name 字段，我们可以运行：

sql 复制代码

SELECT extract_claim_from_jwt(
    'eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6ImExZmIyY2NjN2FiMjBiMDYyNzJmNGUxMjIwZDEwZmZlIn0.eyJpc3MiOiJodHRwczovL2lkcC5sb2NhbCIsImF1ZCI6Im15X2NsaWVudF9hcHAiLCJuYW1lIjoiR2lvcmdpIERhbGFraXNodmlsaSIsInN1YiI6IjViZTg2MzU5MDczYzQzNGJhZDJkYTM5MzIyMjJkYWJlIiwiYWRtaW4iOnRydWUsImV4cCI6MTc2NjU5MTI2NywiaWF0IjoxNzY2NTkwOTY3fQ.N7h2xc4rgS4oPo8IO9wyG1lnr2wqTUC80YudWTXp7rXmU2JdsUiweKmuYVVbygdJAR4PJmbQtak4_VuZg2fZFILVpzDyLvGITfUW_18XuDQ_SIm3VlfAuHOVHfruuvvSAfjUkTW2Jlrv3ihFYgusV58vjhcVFHssOGMEbtMNo10Jf62dczVVGNZXh_OOLS0nTLffhY94sZddqQIE56W8xhLK5YMO4gO8voMzhUwDwucnVvyNfui38MPDNdTSKjn3Ab0hG8jzOVhbYSCHf0eQsbxPzGtXUCJobScWDb78IphFWec6W4ugIYp5CMh3C_noQi94NYjQg2P-AJ5FLCKzKA',
    'name'
);

这将返回 Giorgi Dalakishvili。让我们测试一下表函数：

sql 复制代码

SELECT *
FROM extract_claims_from_jwt(
    'eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6ImExZmIyY2NjN2FiMjBiMDYyNzJmNGUxMjIwZDEwZmZlIn0.eyJpc3MiOiJodHRwczovL2lkcC5sb2NhbCIsImF1ZCI6Im15X2NsaWVudF9hcHAiLCJuYW1lIjoiR2lvcmdpIERhbGFraXNodmlsaSIsInN1YiI6IjViZTg2MzU5MDczYzQzNGJhZDJkYTM5MzIyMjJkYWJlIiwiYWRtaW4iOnRydWUsImV4cCI6MTc2NjU5MTI2NywiaWF0IjoxNzY2NTkwOTY3fQ.N7h2xc4rgS4oPo8IO9wyG1lnr2wqTUC80YudWTXp7rXmU2JdsUiweKmuYVVbygdJAR4PJmbQtak4_VuZg2fZFILVpzDyLvGITfUW_18XuDQ_SIm3VlfAuHOVHfruuvvSAfjUkTW2Jlrv3ihFYgusV58vjhcVFHssOGMEbtMNo10Jf62dczVVGNZXh_OOLS0nTLffhY94sZddqQIE56W8xhLK5YMO4gO8voMzhUwDwucnVvyNfui38MPDNdTSKjn3Ab0hG8jzOVhbYSCHf0eQsbxPzGtXUCJobScWDb78IphFWec6W4ugIYp5CMh3C_noQi94NYjQg2P-AJ5FLCKzKA'
);

这将返回：

claim_name	claim_value
iss	https://idp.local
aud	my_client_app
name	Giorgi Dalakishvili
sub	5be86359073c434bad2da3932222dabe
admin	true
exp	1766591267
iat	1766590967

DuckDB.ExtensionKit 工作原理

DuckDB.ExtensionKit 依赖于几个现代 C# 语言和运行时特性，以高效地将 DuckDB 的 C 扩展 API 桥接到托管代码。这些特性使得在 C# 中构建原生扩展成为可能，而无需在加载时引入托管运行时依赖。

函数指针

DuckDB 的 C 扩展 API 被暴露为一个带版本号的函数表：一个大的结构体 duckdb_ext_api_v1，其字段是 C 函数指针（例如，duckdb_open，duckdb_register_scalar_function，duckdb_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-x64，osx-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 现有的扩展接口，我们可以在高级语言中编写扩展，而无需放弃对原生边界的控制。