TDengine C# Connector
TDengine.Connector
是 TDengine 提供的 C# 语言连接器。C# 开发人员可以通过它开发存取 TDengine 集群数据的 C# 应用软件。
连接方式
TDengine.Connector
提供两种形式的连接器
- 原生连接,通过 TDengine 客户端驱动程序(taosc)原生连接 TDengine 实例,支持数据写入、查询、数据订阅、schemaless 接口和参数绑定接口等功能。
- Websocket 连接,通过 taosAdapter 提供的 Websocket 接 口连接 TDengine 实例,WebSocket 连接实现的功能集合和原生连接有少量不同。(自 v3.0.1 起)
连接方式的详细介绍请参考:连接器建立连接的方式
兼容性
TDengine.Connector
3.1.0 版本进行了完整的重构,不再兼容 3.0.2 及以前版本。3.0.2 文档请参考 nugetTDengine.Connector
3.x 不兼容 TDengine 2.x,如果在运行 TDengine 2.x 版本的环境下需要使用 C# 连接器请使用 TDengine.Connector 的 1.x 版本。
支持的平台
支持的平台和 TDengine 客户端驱动支持的平台一致。
warning
TDengine 不再支持 32 位 Windows 平台。
版本支持
Connector 版本 | TDengine 版本 | 主要功能 |
---|---|---|
3.1.3 | 3.2.1.0/3.1.1.18 | 支持 WebSocket 自动重连 |
3.1.2 | 3.2.1.0/3.1.1.18 | 修复 schemaless 资源释放 |
3.1.1 | 3.2.1.0/3.1.1.18 | 支持 varbinary 和 geometry 类型 |
3.1.0 | 3.2.1.0/3.1.1.18 | WebSocket 使用原生实现 |
处理异常
TDengine.Connector
会抛出异常,应用程序需要处理异常。taosc 异常类型 TDengineError
,包含错误码和错误信息,应用程序可以根据错误码和错误信息进行处理。
TDengine DataType 和 C# DataType
TDengine 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 (utf-8编码) |
JSON | byte[] |
VARBINARY | byte[] |
GEOMETRY | byte[] |
note
JSON 类型仅在 tag 中支持。
安装步骤
安装前准备
安装连接器
可以在当前 .NET 项目的路径下,通过 dotnet CLI 添加 Nuget package TDengine.Connector
到当前项目。
dotnet add package TDengine.Connector
也可以修改当前项目的 .csproj
文件,添加如下 ItemGroup。
<ItemGroup>
<PackageReference Include="TDengine.Connector" Version="3.1.*" />
</ItemGroup>
建立连接
- 原生连接
- WebSocket 连接
var builder = new ConnectionStringBuilder("host=localhost;port=6030;username=root;password=taosdata");
using (var client = DbDriver.Open(builder))
{
Console.WriteLine("connected");
}
var builder = new ConnectionStringBuilder("protocol=WebSocket;host=localhost;port=6041;useSSL=false;username=root;password=taosdata");
using (var client = DbDriver.Open(builder))
{
Console.WriteLine("connected");
}
ConnectionStringBuilder 支持的参数如下:
- protocol: 连接协议,可选值为 Native 或 WebSocket,默认为 Native
- host: TDengine 或 taosadapter 运行实例的地址
- port: TDengine 或 taosadapter 运行实例的端口
- 当 protocol 为 WebSocket 时 useSSL 为 false 时,port 默认为 6041
- 当 protocol 为 WebSocket 时 useSSL 为 true 时,port 默认为 443
- useSSL: 是否使用 SSL 连接,仅当 protocol 为 WebSocket 时有效,默认为 false
- token: 连接 TDengine cloud 的 token,仅当 protocol 为 WebSocket 时有效
- username: 连接 TDengine 的用户名
- password: 连接 TDengine 的密码
- db: 连接 TDengine 的数据库
- timezone: 解析时间结果的时区,默认为
TimeZoneInfo.Local
,使用TimeZoneInfo.FindSystemTimeZoneById
方法解析字符串为TimeZoneInfo
对象。 - connTimeout: WebSocket 连接超时时间,仅当 protocol 为 WebSocket 时有效,默认为 1 分钟,使用
TimeSpan.Parse
方法解析字符串为TimeSpan
对象。 - readTimeout: WebSocket 读超时时间,仅当 protocol 为 WebSocket 时有效,默认为 5 分钟,使用
TimeSpan.Parse
方法解析字符串为TimeSpan
对象。 - writeTimeout: WebSocket 写超时时间,仅当 protocol 为 WebSocket 时有效,默认为 10 秒,使用
TimeSpan.Parse
方法解析字符串为TimeSpan
对象。 - autoReconnect: 是否自动重连(连接器版本 3.1.3 及以上生效),默认为 false
注意:启用自动重连仅对简单执行 SQL 语句以及 无模式写入、数据订阅有效。对于参数绑定无效。自动重连仅对连接建立时通过参数指定数据库有效,对后面的
use db
语句切换数据库无效。
- reconnectRetryCount: 重连次数(连接器版本 3.1.3 及以上生效),默认为 3
- reconnectIntervalMs: 重连间隔时间(连接器版本 3.1.3 及以上生效),默认为 2000
指定 URL 和 Properties 获取连接
C# 连接器不支持此功能
配置参数的优先级
C# 连接器不支持此功能
使用示例
创建数据库和表
- 原生连接
- WebSocket 连接
using System;
using System.Text;
using TDengine.Driver;
using TDengine.Driver.Client;
namespace NativeQuery
{
internal class Query
{
public static void Main(string[] args)
{
var builder = new ConnectionStringBuilder("host=localhost;port=6030;username=root;password=taosdata");
using (var client = DbDriver.Open(builder))
{
try
{
client.Exec("create database power");
client.Exec("CREATE STABLE power.meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS (groupId INT, location BINARY(24))");
}
catch (Exception e)
{
Console.WriteLine(e.ToString());
throw;
}
}
}
}
}
using System;
using System.Text;
using TDengine.Driver;
using TDengine.Driver.Client;
namespace WSQuery
{
internal class Query
{
public static void Main(string[] args)
{
var builder = new ConnectionStringBuilder("protocol=WebSocket;host=localhost;port=6041;useSSL=false;username=root;password=taosdata");
using (var client = DbDriver.Open(builder))
{
try
{
client.Exec("create database power");
client.Exec("CREATE STABLE power.meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS (groupId INT, location BINARY(24))");
}
catch (Exception e)
{
Console.WriteLine(e.ToString());
throw;
}
}
}
}
}