TDengine C# 语言连接器进阶指南

本指南面向已完成"能连通、能读写"的开发者，补齐高级用法与易踩坑点。

1. 连接参数进阶与调优

WebSocket 连接增强参数

WebSocket 连接除基础参数外，还支持：

connTimeout：连接超时（默认 1 分钟）
readTimeout：读取超时（默认 5 分钟）
writeTimeout：发送超时（默认 10 秒）
enableCompression：是否启用压缩
autoReconnect：是否自动重连
reconnectRetryCount / reconnectIntervalMs：重连次数与间隔
token：TDengine Cloud Token
useSSL：是否启用 SSL

示例连接字符串：

text 复制代码

protocol=WebSocket;host=127.0.0.1;port=6041;useSSL=false;enableCompression=true;autoReconnect=true;reconnectIntervalMs=10;reconnectRetryCount=5

连接级别时区（3.1.8+）

仅支持 .NET 6+，仅支持 IANA 时区格式（如 America/New_York）
与 timezone 互斥
Windows 平台原生连接不支持

2. RequestId 与可观测性

部分 API 支持传入 reqId，便于日志/链路追踪。

csharp 复制代码

using TDengine.Driver;
using TDengine.Driver.Client;

var builder = new ConnectionStringBuilder("host=localhost;port=6030;username=root;password=taosdata");
using (var client = DbDriver.Open(builder))
{
    using (var rows = client.Query("SELECT ts, current FROM power.meters LIMIT 1", 3))
    {
        while (rows.Read()) { /*...*/ }
    }
}

无模式写入时可通过 ReqId.GetReqId() 生成请求 ID（见第 4 节）。

3. 批量写入：Stmt 绑定

高吞吐写入推荐使用 Stmt 批量绑定。示例来自官方 stmtInsert：

csharp 复制代码

using TDengine.Driver;
using TDengine.Driver.Client;

var builder = new ConnectionStringBuilder("host=127.0.0.1;port=6030;username=root;password=taosdata");
using (var client = DbDriver.Open(builder))
{
    client.Exec("CREATE DATABASE IF NOT EXISTS power");
    client.Exec("USE power");
    client.Exec("CREATE STABLE IF NOT EXISTS meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS (groupId INT, location BINARY(24))");

    using (var stmt = client.StmtInit())
    {
        string sql = "INSERT INTO ? USING meters TAGS(?,?) VALUES (?,?,?,?)";
        stmt.Prepare(sql);
        stmt.SetTableName("d_bind_1");
        stmt.SetTags(new object[] { 1, "location_1" });
        stmt.BindRow(new object[] { DateTime.Now, 12.3f, 220, 0.32f });
        stmt.AddBatch();
        stmt.Exec();
        Console.WriteLine($"Inserted: {stmt.Affected()}");
    }
}

完整示例见 stmtInsert/Program.cs。

4. 无模式写入（Schemaless）

支持 Influx Line Protocol / OpenTSDB Telnet / JSON。

csharp 复制代码

using TDengine.Driver;
using TDengine.Driver.Client;

var lineDemo = "meters,groupid=2,location=California.SanFrancisco current=10.3000002f64,voltage=219i32,phase=0.31f64 1626006833639";
var telnetDemo = "metric_telnet 1707095283260 4 host=host0 interface=eth0";
var jsonDemo = "{\"metric\": \"metric_json\",\"timestamp\": 1626846400,\"value\": 10.3, \"tags\": {\"groupid\": 2, \"location\": \"California.SanFrancisco\", \"id\": \"d1001\"}}";

var builder = new ConnectionStringBuilder("protocol=WebSocket;host=127.0.0.1;port=6041;username=root;password=taosdata");
using (var client = DbDriver.Open(builder))
{
    client.Exec("CREATE DATABASE IF NOT EXISTS power");
    client.Exec("USE power");
    client.SchemalessInsert(new[] { lineDemo }, TDengineSchemalessProtocol.TSDB_SML_LINE_PROTOCOL,
        TDengineSchemalessPrecision.TSDB_SML_TIMESTAMP_MILLI_SECONDS, 0, ReqId.GetReqId());
    client.SchemalessInsert(new[] { telnetDemo }, TDengineSchemalessProtocol.TSDB_SML_TELNET_PROTOCOL,
        TDengineSchemalessPrecision.TSDB_SML_TIMESTAMP_MILLI_SECONDS, 0, ReqId.GetReqId());
    client.SchemalessInsert(new[] { jsonDemo }, TDengineSchemalessProtocol.TSDB_SML_JSON_PROTOCOL,
        TDengineSchemalessPrecision.TSDB_SML_TIMESTAMP_NOT_CONFIGURED, 0, ReqId.GetReqId());
}

完整示例见 wssml/Program.cs。

5. TMQ 订阅与消费

适用于流式消费场景。核心步骤：创建 consumer、订阅 topic、消费消息、提交 offset。

csharp 复制代码

using TDengine.TMQ;

var cfg = new Dictionary<string, string>()
{
    { "td.connect.port", "6030" },
    { "auto.offset.reset", "latest" },
    { "msg.with.table.name", "true" },
    { "enable.auto.commit", "true" },
    { "auto.commit.interval.ms", "1000" },
    { "group.id", "group1" },
    { "client.id", "client1" },
    { "td.connect.ip", "127.0.0.1" },
    { "td.connect.user", "root" },
    { "td.connect.pass", "taosdata" },
};

IConsumer<Dictionary<string, object>> consumer = new ConsumerBuilder<Dictionary<string, object>>(cfg).Build();
consumer.Subscribe(new List<string>() { "topic_meters" });

using (var cr = consumer.Consume(100))
{
    if (cr != null)
    {
        foreach (var message in cr.Message)
        {
            Console.WriteLine($"{message.Value["ts"]}, {message.Value["current"]}");
        }
    }
}

完整示例见 subscribe/Program.cs。

6. 时间类型与参数绑定注意事项

DateTime.Kind == Unspecified 不可用于绑定（会导致 UTC 转换错误）。
3.1.8+ 支持 DateTimeOffset 与 long（与数据库时间精度一致）。
如需统一跨平台时区，优先使用 IANA 时区（如 Asia/Shanghai）。

7. 资源与性能最佳实践

使用 using 管理连接、结果集与消费者，确保及时释放。
大批量写入优先用 Stmt 或无模式写入；避免逐条 Exec。
WebSocket 大量数据可开启 enableCompression，降低带宽。
异常统一捕获 TDengineError，打印 Code 与 Error。

8. 参考与更多示例

连接器参考文档：https://docs.taosdata.com/tdengine-reference/client-libraries/csharp/
示例代码目录：https://github.com/taosdata/TDengine/tree/main/docs/examples/csharp

关于 TDengine

TDengine 专为物联网IoT平台、工业大数据平台设计。其中，TDengine TSDB 是一款高性能、分布式的时序数据库（Time Series Database），同时它还带有内建的缓存、流式计算、数据订阅等系统功能；TDengine IDMP 是一款AI原生工业数据管理平台，它通过树状层次结构建立数据目录，对数据进行标准化、情景化，并通过 AI 提供实时分析、可视化、事件管理与报警等功能。