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

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

1. 连接参数进阶与调优

WebSocket 连接增强参数

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

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

示例连接字符串：

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，便于日志/链路追踪。

usingTDengine.Driver;usingTDengine.Driver.Client;varbuilder=newConnectionStringBuilder("host=localhost;port=6030;username=root;password=taosdata");using(varclient=DbDriver.Open(builder)){using(varrows=client.Query("SELECT ts, current FROM power.meters LIMIT 1",3)){while(rows.Read()){/*...*/}}}

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

3. 批量写入：Stmt 绑定

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

usingTDengine.Driver;usingTDengine.Driver.Client;varbuilder=newConnectionStringBuilder("host=127.0.0.1;port=6030;username=root;password=taosdata");using(varclient=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(varstmt=client.StmtInit()){stringsql="INSERT INTO ? USING meters TAGS(?,?) VALUES (?,?,?,?)";stmt.Prepare(sql);stmt.SetTableName("d_bind_1");stmt.SetTags(newobject[]{1,"location_1"});stmt.BindRow(newobject[]{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。

usingTDengine.Driver;usingTDengine.Driver.Client;varlineDemo="meters,groupid=2,location=California.SanFrancisco current=10.3000002f64,voltage=219i32,phase=0.31f64 1626006833639";vartelnetDemo="metric_telnet 1707095283260 4 host=host0 interface=eth0";varjsonDemo="{\"metric\": \"metric_json\",\"timestamp\": 1626846400,\"value\": 10.3, \"tags\": {\"groupid\": 2, \"location\": \"California.SanFrancisco\", \"id\": \"d1001\"}}";varbuilder=newConnectionStringBuilder("protocol=WebSocket;host=127.0.0.1;port=6041;username=root;password=taosdata");using(varclient=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。

usingTDengine.TMQ;varcfg=newDictionary<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=newConsumerBuilder<Dictionary<string,object>>(cfg).Build();consumer.Subscribe(newList<string>(){"topic_meters"});using(varcr=consumer.Consume(100)){if(cr!=null){foreach(varmessageincr.Message){Console.WriteLine($"{message.Value["ts"]},{message.Value["current"]}");}}}