Apache IoTDB C#语言客户端

NuGet Version NuGet Downloads

概览

本仓库是Apache IoTDB的C#语言客户端,与其他语言支持相同语义的用户接口。

Apache IoTDB website: https://iotdb.apache.org

Apache IoTDB Github: https://github.com/apache/iotdb

如何安装

从NuGet Package安装

我们为CSharp用户准备了NuGet包，用户可直接通过.NET CLI进行客户端安装，NuGet包链接如下,命令行中运行如下命令即可完成安装

我们为 C# 用户准备了一个 Nuget 包。用户可以直接通过 .NET CLI 进行客户端安装。命令行中运行如下命令即可完成安装

dotnet add package Apache.IoTDB

详情请访问 NuGet 上的包。

[!NOTE] 请注意，Apache.IoTDB这个包仅支持大于.net framework 4.6.1的版本。

环境准备

.NET SDK Version >= 5.0
.NET Framework >= 4.6.1

如何使用 (快速上手)

用户可以通过参考Apache-IoTDB-Client-CSharp-UserCase目录下的用例快速入门。这些用例提供了客户端的基本功能和用法的参考。

对于希望深入了解客户端用法并探索更高级特性的用户，samples目录包含了额外的代码示例。

TLS 和 mTLS

通过 SetUseSsl(true) 开启 TLS。C# 客户端使用 .NET 的证书模型，不直接读取 Java truststore；如果证书按 JDK 17 的 Java/keytool 文档生成，client.keystore 默认就是 PKCS#12，可以直接作为客户端证书文件使用，并直接使用 ca.crt 作为信任根。

keytool 产物	C# 客户端用法
`ca.crt`	传给 `SetRootCertificatePath` / `RootCertificatePath`，用于信任服务端证书
`client.keystore`	包含客户端私钥和客户端证书；JDK 17 默认是 PKCS#12，直接传给 `SetClientCertificatePath`
`client.truststore`	Java 客户端的 truststore；C# 侧用 `ca.crt`，不需要这个文件
`server.truststore`	服务端用于信任客户端证书，不是 C# 客户端参数

配置 RootCertificatePath 后，Host / DataSource 必须匹配服务端证书 SAN。如果使用 IP 地址连接，服务端证书需要包含对应的 IP SAN。

只有在复用旧版 JDK 生成的 JKS 文件，或显式使用 -storetype JKS 生成 keystore 时，才需要先转换为 PKCS#12：

$KT -importkeystore \
  -srckeystore client.keystore \
  -srcstorepass $PWD \
  -srcalias client \
  -destkeystore client.p12 \
  -deststoretype PKCS12 \
  -deststorepass $PWD \
  -destkeypass $PWD \
  -destalias client

C# builder 示例：

var sessionPool = new SessionPool.Builder()
    .SetHost("127.0.0.1")
    .SetPort(6667)
    .SetUseSsl(true)
    .SetRootCertificatePath("tls-certs/ca.crt")
    .SetClientCertificatePath("tls-certs/client.keystore")
    .SetClientCertificatePassword("IoTDB")
    .Build();

ADO.NET 连接字符串也支持相同配置：

DataSource=127.0.0.1;Port=6667;UseSsl=True;RootCertificatePath=tls-certs/ca.crt;ClientCertificatePath=tls-certs/client.keystore;ClientCertificatePassword=IoTDB

iotdb-client-csharp的开发者环境要求

.NET SDK Version >= 5.0
.NET Framework >= 4.6.1
ApacheThrift >= 0.14.1
NLog >= 4.7.9

操作系统

Linux、MacOS 或其他类 Unix 系统
Windows + Bash (WSL、cygwin、Git Bash)

命令行工具

dotnet CLI
Thrift

代码格式化

本项目使用 dotnet format 基于 .editorconfig 规则来强制执行一致的代码风格。

本地检查格式

dotnet format --verify-no-changes

自动修复格式问题

dotnet format

CI 流水线会在所有 Pull Request 上自动检查代码格式。请确保在提交 PR 之前代码格式正确。

在 nuget.org 上发布你自己的客户端

你可以在这个文档中找到如何发布