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

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

1. 准备环境

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

2. 安装连接器

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

xml 复制代码

<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>

或使用命令行：

bash 复制代码

+dotnet add package TDengine.Connector

:::note

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

:::

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

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

原生连接示例：

text 复制代码

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

WebSocket 连接示例：

text 复制代码

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. 最小连接示例

csharp 复制代码

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

csharp 复制代码

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

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

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

csharp 复制代码

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 提供实时分析、可视化、事件管理与报警等功能。