Apache IoTDB C# 原生接口保姆级教程：从环境搭建到全接口实战
Apache IoTDB C# 原生接口保姆级教程：从环境搭建到全接口实战
大家好，最近很多做物联网、时序数据的朋友问我：C# 项目怎么对接 Apache IoTDB？
今天就把完整流程、代码示例、接口说明一次性讲透，照着做就能跑通。
一、先看环境要求
用 C# 原生客户端之前，先把环境配好：
- .NET SDK ≥ 5.0 或 .NET Framework 4.x
- Thrift ≥ 0.14.1
- NLog ≥ 4.7.9
版本不匹配很容易报奇怪的异常，建议直接按上面的标准来。
二、NuGet 依赖安装（超简单）
安装客户端用 NuGet 包管理器或 .NET CLI 都行，我直接给你最常用的命令。
1. 安装最新版
如果你用的是 .NET 5.0 及以上，一行命令搞定：
dotnetaddpackage Apache.IoTDB2. 安装指定旧版本
比如要装 0.12.1.2 版本：
dotnetaddpackage Apache.IoTDB--version0.12.1.2这里有个关键提醒：
千万别用高版本客户端去连低版本服务端！大概率连不上、报参数错误、数据异常，一定要版本对应。
三、快速入门：完整可运行示例
直接给你一套复制就能跑的代码，包含：连接、建时间序列、Record 写入、Tablet 写入、关闭连接。
// 参数配置stringhost="localhost";intport=6667;intpool_size=2;// 初始化连接池varsession_pool=newSessionPool(host,port,pool_size);// 打开会话awaitsession_pool.Open(false);// 创建时间序列awaitsession_pool.CreateTimeSeries("root.test_group.test_device.ts1",TSDataType.TEXT,TSEncoding.PLAIN,Compressor.UNCOMPRESSED);awaitsession_pool.CreateTimeSeries("root.test_group.test_device.ts2",TSDataType.BOOLEAN,TSEncoding.PLAIN,Compressor.UNCOMPRESSED);awaitsession_pool.CreateTimeSeries("root.test_group.test_device.ts3",TSDataType.INT32,TSEncoding.PLAIN,Compressor.UNCOMPRESSED);// --------------- Record 单行写入 ---------------varmeasures=newList<string>{"ts1","ts2","ts3"};varvalues=newList<object>{"test_text",true,(int)123};vartimestamp=1;varrowRecord=newRowRecord(timestamp,values,measures);awaitsession_pool.InsertRecordAsync("root.test_group.test_device",rowRecord);// --------------- Tablet 批量写入 ---------------vartimestamp_lst=newList<long>{timestamp+1};varvalue_lst=newList<object>{"iotdb",true,(int)12};vartablet=newTablet("root.test_group.test_device",measures,value_lst,timestamp_lst);awaitsession_pool.InsertTabletAsync(tablet);// 关闭会话awaitsession_pool.Close();把这段代码放进你的异步方法里，直接运行就能看到效果。
四、全量接口详细说明（开发必备）
IoTDB C# 客户端核心就是SessionPool 连接池，支持并发、线程安全，pool_size=1 时等价于单 Session，项目里优先用 SessionPool 就对了。
下面按功能分类，把常用接口一次性列全。
4.1 基础接口
| 方法名 | 参数 | 作用 | 示例 |
|---|---|---|---|
| Open | bool | 打开会话 | session_pool.Open(false) |
| Close | null | 关闭会话 | session_pool.Close() |
| IsOpen | null | 查看会话状态 | session_pool.IsOpen() |
| OpenDebugMode | LoggingConfiguration | 开启调试 | session_pool.OpenDebugMode() |
| CloseDebugMode | null | 关闭调试 | session_pool.CloseDebugMode() |
| SetTimeZone | string | 设置时区 | session_pool.SetTimeZone(“+08:00”) |
| GetTimeZone | null | 获取时区 | session_pool.GetTimeZone() |
4.2 元数据接口
主要用来管理存储组、时间序列：
| 方法名 | 参数 | 作用 | 示例 |
|---|---|---|---|
| SetStorageGroup | string | 创建存储组 | session_pool.SetStorageGroup(“root.test_group”) |
| CreateTimeSeries | 路径+类型+编码+压缩 | 创建单条时序 | CreateTimeSeries(…) |
| CreateMultiTimeSeriesAsync | 多个列表 | 批量创建时序 | CreateMultiTimeSeriesAsync(…) |
| CheckTimeSeriesExistsAsync | 路径 | 判断时序是否存在 | CheckTimeSeriesExistsAsync(path) |
4.3 写入接口（重点）
C# 客户端支持Record和Tablet两种写入方式，适用场景不一样：
4.3.1 RowRecord（适合单行写入）
构造方式：
varrowRecord=newRowRecord(时间戳,值列表,测量点列表);常用方法：
- InsertRecordAsync：单条记录写入
- InsertRecordsAsync：多条记录写入
- InsertRecordsOfOneDeviceAsync：同一设备批量写入
- InsertRecordsOfOneDeviceSortedAsync：有序批量写入
- TestInsertXXXAsync：测试写入（不真正落库）
4.3.2 Tablet（适合批量块写入）
构造方式：
vartablet=newTablet(设备ID,测量点列表,值二维列表,时间戳列表);常用方法：
- InsertTabletAsync：单 Tablet 写入
- InsertTabletsAsync：批量 Tablet 写入
- TestInsertTabletAsync：测试单 Tablet
- TestInsertTabletsAsync：测试多 Tablet
小经验：单条用 Record，大量连续数据优先用 Tablet，性能差很多。
4.4 查询接口
| 方法名 | 参数 | 作用 | 示例 |
|---|---|---|---|
| ExecuteQueryStatementAsync | SQL 语句 | 查询语句 | session_pool.ExecuteQueryStatementAsync("select * from root.97209_TEST_CSHARP_CLIENT_GROUP.TEST_CSHARP_CLIENT_DEVICE where time<15"); |
| ExecuteNonQueryStatementAsync | SQL 语句 | 非查询（建删改） | create timeseries … |
4.5 删除接口
| 方法名 | 参数 | 作用 |
|---|---|---|
| DeleteStorageGroupAsync | string | 删单个存储组 |
| DeleteStorageGroupsAsync | List | 删多个存储组 |
| DeleteTimeSeriesAsync | string / List | 删时间序列 |
| DeleteDataAsync | 路径列表, 起始, 结束 | 按时间删数据 |
总结
这篇文章把Apache IoTDB C# 原生接口从 0 到 1 讲完了，核心要点帮你捋一遍：
- 环境认准：.NET ≥5.0 / Framework 4.x + Thrift ≥0.14.1 + NLog ≥4.7.9；
- 安装用 NuGet 命令，客户端与服务端版本必须匹配；
- 优先用SessionPool连接池，线程安全、支持并发；
- 写入分两种：RowRecord 适合单行，Tablet 适合批量块写入；
- 全套接口覆盖：基础连接、元数据、写入、查询、删除，日常开发完全够用。
照着教程配环境、跑示例、改接口，C# 项目快速接入 IoTDB 时序数据库完全没压力。
🌐 附：IoTDB的各大版本
📄 Apache IoTDB 是一款工业物联网时序数据库管理系统，采用端边云协同的轻量化架构，支持一体化的物联网时序数据收集、存储、管理与分析 ，具有多协议兼容、超高压缩比、高通量读写、工业级稳定、极简运维等特点。
| 版本 | IoTDB 二进制包 | IoTDB 源代码 | 发布说明 |
|---|---|---|---|
| 2.0.5 | - All-in-one - AINode - SHA512 - ASC | - 源代码 - SHA512 - ASC | release notes |
| 1.3.5 | - All-in-one - AINode - SHA512 - ASC | - 源代码 - SHA512 - ASC | release notes |
| 0.13.4 | - All-in-one - Grafana 连接器 - Grafana 插件 - SHA512 - ASC | - 源代码 - SHA512 - ASC | release notes |
✨ 目前最新版本为2.0.7，去获取：https://archive.apache.org/dist/iotdb/
联系博主
xcLeigh 博主，全栈领域优质创作者，博客专家，目前，活跃在CSDN、微信公众号、小红书、知乎、掘金、快手、思否、微博、51CTO、B站、腾讯云开发者社区、阿里云开发者社区等平台，全网拥有几十万的粉丝，全网统一IP为xcLeigh。希望通过我的分享，让大家能在喜悦的情况下收获到有用的知识。主要分享编程、开发工具、算法、技术学习心得等内容。很多读者评价他的文章简洁易懂，尤其对于一些复杂的技术话题，他能通过通俗的语言来解释，帮助初学者更好地理解。博客通常也会涉及一些实践经验，项目分享以及解决实际开发中遇到的问题。如果你是开发领域的初学者，或者在学习一些新的编程语言或框架，关注他的文章对你有很大帮助。
亲爱的朋友，无论前路如何漫长与崎岖，都请怀揣梦想的火种，因为在生活的广袤星空中，总有一颗属于你的璀璨星辰在熠熠生辉，静候你抵达。
愿你在这纷繁世间，能时常收获微小而确定的幸福，如春日微风轻拂面庞，所有的疲惫与烦恼都能被温柔以待，内心永远充盈着安宁与慰藉。
至此，文章已至尾声，而您的故事仍在续写，不知您对文中所叙有何独特见解？期待您在心中与我对话，开启思想的新交流。
💞 关注博主 🌀 带你实现畅游前后端！
🏰 大屏可视化 🌀 带你体验酷炫大屏！
💯 神秘个人简介 🌀 带你体验不一样得介绍！
🥇 从零到一学习Python 🌀 带你玩转Python技术流！
🏆 前沿应用深度测评 🌀 前沿AI产品热门应用在线等你来发掘！
💦注：本文撰写于CSDN平台,作者：xcLeigh（所有权归作者所有），https://xcleigh.blog.csdn.net/，如果相关下载没有跳转，请查看这个地址，相关链接没有跳转，皆是抄袭本文，转载请备注本文原地址。
📣 亲，码字不易，动动小手，欢迎点赞 ➕ 收藏，如 🈶 问题请留言（或者关注下方公众号，看见后第一时间回复，还有海量编程资料等你来领！），博主看见后一定及时给您答复 💌💌💌