320 lines
11 KiB
Plaintext
320 lines
11 KiB
Plaintext
---
|
||
toc_max_heading_level: 4
|
||
sidebar_label: C#
|
||
title: C# Connector
|
||
---
|
||
|
||
import Tabs from '@theme/Tabs';
|
||
import TabItem from '@theme/TabItem';
|
||
|
||
import Preparation from "./_preparation.mdx"
|
||
import CSInsert from "../07-develop/03-insert-data/_cs_sql.mdx"
|
||
import CSInfluxLine from "../07-develop/03-insert-data/_cs_line.mdx"
|
||
import CSOpenTSDBTelnet from "../07-develop/03-insert-data/_cs_opts_telnet.mdx"
|
||
import CSOpenTSDBJson from "../07-develop/03-insert-data/_cs_opts_json.mdx"
|
||
import CSQuery from "../07-develop/04-query-data/_cs.mdx"
|
||
import CSAsyncQuery from "../07-develop/04-query-data/_cs_async.mdx"
|
||
|
||
`TDengine.Connector` 是 TDengine 提供的 C# 语言连接器。C# 开发人员可以通过它开发存取 TDengine 集群数据的 C# 应用软件。
|
||
|
||
`TDengine.Connector` 连接器支持通过 TDengine 客户端驱动（taosc）建立与 TDengine 运行实例的连接，提供数据写入、查询、数据订阅、schemaless 数据写入、参数绑定接口数据写入等功能。 `TDengine.Connector` 自 v3.0.1 起还支持 WebSocket，通过 DSN 建立 WebSocket 连接，提供数据写入、查询、参数绑定接口数据写入等功能。
|
||
|
||
本文介绍如何在 Linux 或 Windows 环境中安装 `TDengine.Connector`，并通过 `TDengine.Connector` 连接 TDengine 集群，进行数据写入、查询等基本操作。
|
||
|
||
注意：`TDengine.Connector` 3.x 不兼容 TDengine 2.x，如果在运行 TDengine 2.x 版本的环境下需要使用 C# 连接器请使用 TDengine.Connector 的 1.x 版本 。
|
||
|
||
`TDengine.Connector` 的源码托管在 [GitHub](https://github.com/taosdata/taos-connector-dotnet/tree/3.0)。
|
||
|
||
## 支持的平台
|
||
|
||
支持的平台和 TDengine 客户端驱动支持的平台一致。
|
||
|
||
:::note
|
||
注意 TDengine 不再支持 32 位 Windows 平台。
|
||
:::
|
||
|
||
## 版本支持
|
||
|
||
请参考[版本支持列表](../#版本支持)
|
||
|
||
## 支持的功能特性
|
||
|
||
<Tabs defaultValue="rest">
|
||
|
||
<TabItem value="native" label="原生连接">
|
||
|
||
1. 连接管理
|
||
2. 普通查询
|
||
3. 连续查询
|
||
4. 参数绑定
|
||
5. 数据订阅（TMQ）
|
||
6. Schemaless
|
||
|
||
</TabItem>
|
||
|
||
<TabItem value="rest" label="WebSocket 连接">
|
||
|
||
1. 连接管理
|
||
2. 普通查询
|
||
3. 连续查询
|
||
4. 参数绑定
|
||
|
||
</TabItem>
|
||
|
||
</Tabs>
|
||
|
||
## 安装步骤
|
||
|
||
### 安装前准备
|
||
|
||
* 安装 [.NET SDK](https://dotnet.microsoft.com/download)
|
||
* [Nuget 客户端](https://docs.microsoft.com/en-us/nuget/install-nuget-client-tools) （可选安装）
|
||
* 安装 TDengine 客户端驱动，具体步骤请参考[安装客户端驱动](../#安装客户端驱动)
|
||
|
||
### 安装 TDengine.Connector
|
||
|
||
<Tabs defaultValue="CLI">
|
||
<TabItem value="CLI" label="使用本地连接">
|
||
|
||
可以在当前 .NET 项目的路径下，通过 dotnet CLI 添加 Nuget package `TDengine.Connector` 到当前项目。
|
||
|
||
``` bash
|
||
dotnet add package TDengine.Connector
|
||
```
|
||
|
||
也可以修改当前项目的 `.csproj` 文件，添加如下 ItemGroup。
|
||
|
||
``` XML
|
||
<ItemGroup>
|
||
<PackageReference Include="TDengine.Connector" Version="3.0.*" />
|
||
</ItemGroup>
|
||
```
|
||
|
||
</TabItem>
|
||
|
||
<TabItem value="source" label="使用 WebSocket 连接">
|
||
|
||
需要修改目标项目的 `.csproj` 项目文件，将 `.nupkg` 中的 `runtimes` 目录中的动态库复制到当前项目的 `$(OutDir)` 目录下。
|
||
|
||
```XML
|
||
<ItemGroup>
|
||
<PackageReference Include="TDengine.Connector" Version="3.0.*" GeneratePathProperty="true" />
|
||
</ItemGroup>
|
||
<Target Name="copyDLLDependency" BeforeTargets="BeforeBuild">
|
||
<ItemGroup>
|
||
<DepDLLFiles Include="$(PkgTDengine_Connector)\runtimes\**\*.*" />
|
||
</ItemGroup>
|
||
<Copy SourceFiles="@(DepDLLFiles)" DestinationFolder="$(OutDir)" />
|
||
</Target>
|
||
```
|
||
|
||
注意：`TDengine.Connector` 自 version>= 3.0.2 的 nuget package 中才会有动态库（ taosws.dll，libtaows.so ）。
|
||
|
||
</TabItem>
|
||
</Tabs>
|
||
|
||
## 建立连接
|
||
|
||
<Tabs defaultValue="rest">
|
||
|
||
<TabItem value="native" label="原生连接">
|
||
|
||
使用 host、username、password、port 等信息建立连接。
|
||
|
||
``` csharp
|
||
using TDengineDriver;
|
||
|
||
namespace TDengineExample
|
||
{
|
||
|
||
internal class EstablishConnection
|
||
{
|
||
static void Main(String[] args)
|
||
{
|
||
string host = "localhost";
|
||
short port = 6030;
|
||
string username = "root";
|
||
string password = "taosdata";
|
||
string dbname = "";
|
||
|
||
var conn = TDengine.Connect(host, username, password, dbname, port);
|
||
if (conn == IntPtr.Zero)
|
||
{
|
||
Console.WriteLine("Connect to TDengine failed");
|
||
}
|
||
else
|
||
{
|
||
Console.WriteLine("Connect to TDengine success");
|
||
}
|
||
TDengine.Close(conn);
|
||
TDengine.Cleanup();
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
</TabItem>
|
||
|
||
<TabItem value="rest" label="WebSocket 连接">
|
||
|
||
使用 DSN 建立 WebSocket 连接 DSN 连接。 描述字符串基本结构如下：
|
||
|
||
```text
|
||
[<protocol>]://[[<username>:<password>@]<host>:<port>][/<database>][?<p1>=<v1>[&<p2>=<v2>]]
|
||
|------------|---|-----------|-----------|------|------|------------|-----------------------|
|
||
| protocol | | username | password | host | port | database | params |
|
||
```
|
||
|
||
各部分意义见下表：
|
||
|
||
* **protocol**: 显示指定以何种方式建立连接，例如：`ws://localhost:6041` 指定以 Websocket 方式建立连接（支持 http/ws ）。
|
||
|
||
* **username/password**: 用于创建连接的用户名及密码（默认 `root/taosdata` ）。
|
||
|
||
* **host/port**: 指定创建连接的服务器及端口，WebSocket 连接默认为 `localhost:6041` 。
|
||
|
||
* **database**: 指定默认连接的数据库名，可选参数。
|
||
|
||
* **params**：其他可选参数。
|
||
|
||
``` csharp
|
||
{{#include docs/examples/csharp/wsConnect/Program.cs}}
|
||
```
|
||
|
||
</TabItem>
|
||
</Tabs>
|
||
|
||
## 使用示例
|
||
|
||
### 写入数据
|
||
|
||
#### SQL 写入
|
||
|
||
<Tabs defaultValue="rest">
|
||
|
||
<TabItem value="native" label="原生连接">
|
||
|
||
<CSInsert />
|
||
|
||
</TabItem>
|
||
|
||
<TabItem value="rest" label="WebSocket 连接">
|
||
|
||
```csharp
|
||
{{#include docs/examples/csharp/wsInsert/Program.cs}}
|
||
```
|
||
|
||
</TabItem>
|
||
|
||
</Tabs>
|
||
|
||
#### InfluxDB 行协议写入
|
||
|
||
<CSInfluxLine />
|
||
|
||
#### OpenTSDB Telnet 行协议写入
|
||
|
||
<CSOpenTSDBTelnet />
|
||
|
||
#### OpenTSDB JSON 行协议写入
|
||
|
||
<CSOpenTSDBJson />
|
||
|
||
#### 参数绑定
|
||
|
||
<Tabs defaultValue="rest">
|
||
|
||
<TabItem value="native" label="原生连接">
|
||
|
||
``` csharp
|
||
{{#include docs/examples/csharp/stmtInsert/Program.cs}}
|
||
```
|
||
|
||
</TabItem>
|
||
|
||
<TabItem value="rest" label="WebSocket 连接">
|
||
|
||
```csharp
|
||
{{#include docs/examples/csharp/wsStmt/Program.cs}}
|
||
```
|
||
|
||
</TabItem>
|
||
|
||
</Tabs>
|
||
|
||
### 查询数据
|
||
|
||
#### 同步查询
|
||
|
||
<Tabs defaultValue="rest">
|
||
|
||
<TabItem value="native" label="原生连接">
|
||
|
||
<CSQuery />
|
||
|
||
</TabItem>
|
||
|
||
<TabItem value="rest" label="WebSocket 连接">
|
||
|
||
```csharp
|
||
{{#include docs/examples/csharp/wsQuery/Program.cs}}
|
||
```
|
||
|
||
</TabItem>
|
||
|
||
</Tabs>
|
||
|
||
#### 异步查询
|
||
|
||
<CSAsyncQuery />
|
||
|
||
### 更多示例程序
|
||
|
||
|示例程序 | 示例程序描述 |
|
||
|--------------------------------------------------------------------------------------------------------------------|--------------------------------------------|
|
||
| [CURD](https://github.com/taosdata/taos-connector-dotnet/blob/3.0/examples/NET6Examples/Query/Query.cs) | 使用 TDengine.Connector 实现的建表、插入、查询示例 |
|
||
| [JSON Tag](https://github.com/taosdata/taos-connector-dotnet/blob/3.0/examples/NET6Examples/JSONTag) | 使用 TDengine.Connector 实现的写入和查询 JSON tag 类型数据的示例 |
|
||
| [stmt](https://github.com/taosdata/taos-connector-dotnet/tree/3.0/examples/NET6Examples/Stmt) | 使用 TDengine.Connector 实现的参数绑定插入和查询的示例 |
|
||
| [schemaless](https://github.com/taosdata/taos-connector-dotnet/blob/3.0/examples/NET6Examples/schemaless) | 使用 TDengine.Connector 实现的使用 schemaless 写入的示例 |
|
||
| [async query](https://github.com/taosdata/taos-connector-dotnet/blob/3.0/examples/NET6Examples/AsyncQuery/QueryAsync.cs) | 使用 TDengine.Connector 实现的异步查询的示例 |
|
||
| [数据订阅（TMQ）](https://github.com/taosdata/taos-connector-dotnet/blob/3.0/examples/NET6Examples/TMQ/TMQ.cs) | 使用 TDengine.Connector 实现的订阅数据的示例 |
|
||
| [Basic WebSocket Usage](https://github.com/taosdata/taos-connector-dotnet/blob/3.0/examples/FrameWork45/WS/WebSocketSample.cs) | 使用 TDengine.Connector 的 WebSocket 基本的示例 |
|
||
| [Basic WebSocket STMT](https://github.com/taosdata/taos-connector-dotnet/blob/3.0/examples/FrameWork45/WS/WebSocketSTMT.cs) | 使用 TDengine.Connector 的 WebSocket STMT 基本的示例 |
|
||
|
||
## 重要更新记录
|
||
|
||
| TDengine.Connector | 说明 |
|
||
|--------------------|--------------------------------|
|
||
| 3.0.2 | 支持 .NET Framework 4.5 及以上，支持 .NET standard 2.0。Nuget Package 包含 WebSocket 动态库。 |
|
||
| 3.0.1 | 支持 WebSocket 和 Cloud，查询，插入，参数绑定。 |
|
||
| 3.0.0 | 支持 TDengine 3.0.0.0，不兼容 2.x。新增接口TDengine.Impl.GetData()，解析查询结果。 |
|
||
| 1.0.7 | 修复 TDengine.Query()内存泄露。 |
|
||
| 1.0.6 | 修复 schemaless 在 1.0.4 和 1.0.5 中失效 bug。 |
|
||
| 1.0.5 | 修复 Windows 同步查询中文报错 bug。 |
|
||
| 1.0.4 | 新增异步查询，订阅等功能。修复绑定参数 bug。 |
|
||
| 1.0.3 | 新增参数绑定、schemaless、 json tag等功能。 |
|
||
| 1.0.2 | 新增连接管理、同步查询、错误信息等功能。 |
|
||
|
||
## 其他说明
|
||
|
||
### 第三方驱动
|
||
|
||
[`IoTSharp.Data.Taos`](https://github.com/IoTSharp/EntityFrameworkCore.Taos) 是一个 TDengine 的 ADO.NET 连接器,其中包含了用于EntityFrameworkCore 的提供程序 IoTSharp.EntityFrameworkCore.Taos 和健康检查组件 IoTSharp.HealthChecks.Taos ，支持 Linux，Windows 平台。该连接器由社区贡献者`麦壳饼@@maikebing` 提供，具体请参考:
|
||
|
||
* 接口下载: <https://github.com/IoTSharp/EntityFrameworkCore.Taos>
|
||
* 用法说明:<https://www.taosdata.com/blog/2020/11/02/1901.html>
|
||
|
||
## 常见问题
|
||
|
||
1. "Unable to establish connection"，"Unable to resolve FQDN"
|
||
|
||
一般是因为 FQDN 配置不正确。可以参考[如何彻底搞懂 TDengine 的 FQDN](https://www.taosdata.com/blog/2021/07/29/2741.html)解决。
|
||
|
||
2. Unhandled exception. System.DllNotFoundException: Unable to load DLL 'taos' or one of its dependencies: 找不到指定的模块。
|
||
|
||
一般是因为程序没有找到依赖的客户端驱动。解决方法为：Windows 下可以将 `C:\TDengine\driver\taos.dll` 拷贝到 `C:\Windows\System32\ ` 目录下，Linux 下建立如下软链接 `ln -s /usr/local/taos/driver/libtaos.so.x.x.x.x /usr/lib/libtaos.so` 即可。
|
||
|
||
## API 参考
|
||
|
||
[API 参考](https://docs.taosdata.com/api/connector-csharp/html/860d2ac1-dd52-39c9-e460-0829c4e5a40b.htm)
|