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