TDengine C# 语言连接器入门指南

本指南汇总官网文档中 C# 初学者应该掌握的基础知识，覆盖安装、连接方式、基本读写、异常处理与数据类型映射。示例代码基于 .NET 6.0。

1. 准备环境

• 确保 TDengine TSDB 服务端可访问。
• 原生连接使用 serverPort（默认 6030）。
• WebSocket 连接需要 taosAdapter，默认端口 6041。

2. 安装连接器

在项目文件中添加 NuGet 依赖：

<ProjectSdk="Microsoft.NET.Sdk"><PropertyGroup><OutputType>Exe</OutputType><TargetFramework>net6.0</TargetFramework><ImplicitUsings>enable</ImplicitUsings><Nullable>enable</Nullable></PropertyGroup><ItemGroup><PackageReferenceInclude="TDengine.Connector"Version="3.1.0"/></ItemGroup></Project>

或使用命令行：

+dotnetaddpackage TDengine.Connector

:::note
以下示例代码基于 .NET 6.0；如使用其他版本，请根据目标框架做适配。
:::

3. 选择连接方式与连接字符串

连接字符串采用key=value形式，参数之间用分号分隔。

• 原生连接示例：

host=127.0.0.1;port=6030;username=root;password=taosdata;protocol=Native

• WebSocket 连接示例：

protocol=WebSocket;host=127.0.0.1;port=6041;useSSL=false;username=root;password=taosdata

常用参数速览

• host：TDengine 实例地址。
• port：端口（原生 6030 / WebSocket 6041）。
• username/password：认证信息。
• protocol：Native或WebSocket（默认 Native）。
• db：连接数据库。
• timezone：查询结果集解析时区。
• connectionTimezone：连接级别时区（3.1.8+，仅 .NET 6+，与timezone互斥）。

更多参数与时区规则请参考 C# 连接器参考文档的“参数规范/时区说明”。

4. 最小连接示例

{{#include docs/examples/csharp/connect/Program.cs:main}}

{{#include docs/examples/csharp/wsConnect/Program.cs:main}}

5. 建库建表、写入与查询

下面示例展示基础的建库建表、插入与查询流程：

usingSystem;usingSystem.Text;usingTDengine.Driver;usingTDengine.Driver.Client;varbuilder=newConnectionStringBuilder("host=localhost;port=6030;username=root;password=taosdata");using(varclient=DbDriver.Open(builder)){client.Exec("CREATE DATABASE IF NOT EXISTS power");client.Exec("CREATE STABLE IF NOT EXISTS power.meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS (groupId INT, location BINARY(24))");client.Exec("INSERT INTO power.d1001 USING power.meters TAGS(2,'California.SanFrancisco') VALUES "+"(NOW + 1a, 10.30000, 219, 0.31000) (NOW + 2a, 12.60000, 218, 0.33000)");using(varrows=client.Query("SELECT ts, current, location FROM power.meters LIMIT 5")){while(rows.Read()){varts=(DateTime)rows.GetValue(0);varcurrent=(float)rows.GetValue(1);varlocation=Encoding.UTF8.GetString((byte[])rows.GetValue(2));Console.WriteLine($"{ts:yyyy-MM-dd HH:mm:ss.fff},{current},{location}");}}}

更完整的插入/查询示例可参考：

• docs/examples/csharp/sqlInsert/Program.cs
• docs/examples/csharp/query/Program.cs

6. 异常处理与错误码

TDengine.Connector会抛出TDengineError，包含错误码与错误信息。建议统一捕获并输出Code与Error字段。TDengine 其他模块的错误码参见 错误码。

7. 数据类型映射（必知）

注意：

• JSON 类型仅在 tag 中支持。
• GEOMETRY 为 WKB 小端字节序。
• DECIMAL 在 C# 使用decimal；当精度超出decimal范围时需用GetString获取。

8. 下一步建议

• 了解更多连接参数与时区行为：见 C# 连接器参考文档“参数规范/时区说明”。
• 查询返回类型：见“数据类型映射”。
• 继续学习 ADO.NET 标准接口、无模式写入、订阅与 stmt：见 C# 连接器参考文档“API 参考”。

关于TDengine

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