本指南汇总官网文档中 C# 初学者应该掌握的基础知识，覆盖安装、连接方式、基本读写、异常处理与数据类型映射。示例代码基于 .NET 6.0。
1. 准备环境
- 确保 TDengine TSDB 服务端可访问。
- 原生连接使用 serverPort（默认 6030）。
- WebSocket 连接需要 taosAdapter，默认端口 6041。
2. 安装连接器
在项目文件中添加 NuGet 依赖：
<Project Sdk="Microsoft.NET.Sdk"><PropertyGroup><OutputType>Exe</OutputType><TargetFramework>net6.0</TargetFramework><ImplicitUsings>enable</ImplicitUsings><Nullable>enable</Nullable></PropertyGroup><ItemGroup><PackageReference Include="TDengine.Connector" Version="3.1.0" /></ItemGroup>
</Project>或使用命令行：
+dotnet add package 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. 建库建表、写入与查询
下面示例展示基础的建库建表、插入与查询流程：
using System;
using System.Text;
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))
{
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 (var rows = client.Query("SELECT ts, current, location FROM power.meters LIMIT 5"))
{
while (rows.Read())
{
var ts = (DateTime)rows.GetValue(0);
var current = (float)rows.GetValue(1);
var location = 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. 数据类型映射（必知）
| TDengine TSDB DataType | C# Type |
|---|---|
| TIMESTAMP | DateTime |
| TINYINT | sbyte |
| SMALLINT | short |
| INT | int |
| BIGINT | long |
| TINYINT UNSIGNED | byte |
| SMALLINT UNSIGNED | ushort |
| INT UNSIGNED | uint |
| BIGINT UNSIGNED | ulong |
| FLOAT | float |
| DOUBLE | double |
| BOOL | bool |
| BINARY | byte[] |
| NCHAR | string |
| JSON | byte[] |
| VARBINARY | byte[] |
| GEOMETRY | byte[] |
| DECIMAL | decimal |
注意：
- 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 提供实时分析、可视化、事件管理与报警等功能。