csharp.mdx

---
sidebar_position: 7
sidebar_label: C#
title: C# Connector
---

## 总体介绍

TDengine.Connector 是 TDengine 提供的 C# 本地客户端驱动连接器。该连接器通过 TDengine 客户端驱动建立本地连接，进而可以访问 TDengine 数据库。目前已支持 TDengine 的绝大部分特性。例如：同步查询、异步查询、管理连接、订阅消费，schemaless 等。

本文介绍如何在 Windows 或 Linux 环境中安装 TDengine.Connector，并通过 TDengine.Connector 连接 TDengine 数据库、进行数据查询、数据写入等基本操作。

TDengine.Connector 目前暂未封装 RESTful 接口，用户可以参考 [RESTful APIs](https://docs.taosdata.com//reference/restful-api/) 文档自行编写。

## 支持的平台

C# 连接器支持的系统有：Linux 64 / Windows x64/ Windows x86

## 版本支持

| TDengine.Connector |             TDengine 版本             | 说明                           |
|--------------------|:-------------------------------------:|--------------------------------|
|        1.0.2       | v2.5.0.x,v2.4.0.x,v2.3.4+ | 支持连接管理、同步查询、错误信息等功能。   |
|        1.0.3       | v2.5.0.x,v2.4.0.x,v2.3.4+ | 新增参数绑定、schemaless, json tag 等功能。 |
|        1.0.4       | v2.5.0.x,v2.4.0.x,v2.3.4+ | 新增异步查询，订阅等功能，修复绑定参数 bug。     |
|        1.0.5       | v2.5.0.x,v2.4.0.x,v2.3.4+ | 修复 Windows 同步查询中文报错 bug。   |
|        1.0.6       | v2.5.0.x,v2.4.0.x,v2.3.4+ | 修复schemaless bug。|

## 支持的特性

### 本地连接

“本地连接”指连接器通过本地客户端驱动程序 taosc 直接与服务端程序 taosd 建立连接。
“本地连接”支持的特新如下：

1. 连接管理
2. 同步查询
3. 异步查询
4. 参数绑定
5. 错误信息
6. 订阅功能
7. Schemaless

## 安装步骤

### 安装前的准备

* 安装 [.NET SDK](https://dotnet.microsoft.com/download)

* 安装 [TDengine 客户端](/reference/connector/#安装客户端驱动)

* 安装 （可选） [Nuget 客户端](https://docs.microsoft.com/en-us/nuget/install-nuget-client-tools)

### 使用 dotnet CLI 安装

使用 C# Connector 连接数据库前，需要具备以下条件：

1. Linux 或 Windows 操作系统
2. .Net 5.0 及以上运行时环境
3. TDengine-client

**注意**：使用 C# 连接器包时需要安装对应的客户端驱动。

- 在 Linux 系统中成功安装 TDengine 客户端之后，TDengine.Connector 依赖的本地客户端驱动 libtaos.so 文件会被自动拷贝至 /usr/lib/libtaos.so，该目录包含在 Linux 自动扫描路径上，无需单独指定。
- 在 Windows 系统中成功安装 TDengine 客户端之后，TDengine.Connector 依赖的本地客户端驱动 taos.dll 文件会自动拷贝到系统默认搜索路径 C:/Windows/System32 下，同样无需单独指定。

**注意**：在 Windows 环境下开发时，需要安装 TDengine 对应的 [Windows 客户端](https://www.taosdata.com/cn/all-downloads/#TDengine-Windows-Client)，Linux 服务器安装完 TDengine 之后默认已安装 client，也可以单独安装 [Linux 客户端](/get-started/) 连接远程 TDengine Server。

#### 使用 dotnet CLI 获取 C# 驱动

可以在当前 .NET 项目的路径下，通过 dotnet 命令引用 Nuget 中发布的 TDengine.Connector 到当前项目。

``` bash
dotnet add package TDengine.Connector
```

#### 使用源码获取 C# 驱动

可以下载 TDengine 的源码，直接引用最新版本的 TDengine.Connector库

```bash
git clone https://github.com/taosdata/TDengine.git
cd TDengine/src/connector/C#/src/
cp -r C#/src/TDengineDriver/ myProject

cd myProject
dotnet add TDengineDriver/TDengineDriver.csproj
```

## 建立连接

### 建立本地连接

``` C#
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();
        }
    }
}

```

## 使用示例

|示例程序                                                                                                               | 示例程序描述                                       |
|--------------------------------------------------------------------------------------------------------------------|--------------------------------------------|
| [C#checker](https://github.com/taosdata/TDengine/tree/develop/examples/C%23/C%23checker)                           | 使用 TDengine.Connector 可以通过 help 命令中提供的参数，测试C# Driver的同步写入和查询    |
| [TDengineTest](https://github.com/taosdata/TDengine/tree/develop/examples/C%23/TDengineTest)                       | 使用 TDengine.Connector 实现的简单写入和查询的示例 |
| [insertCn](https://github.com/taosdata/TDengine/tree/develop/examples/C%23/insertCn)                               | 使用 TDengine.Connector 实现的写入和查询中文字符的示例    |
| [jsonTag](https://github.com/taosdata/TDengine/tree/develop/examples/C%23/jsonTag)                                 | 使用 TDengine.Connector 实现的写入和查询 json tag 类型数据的示例 |
| [stmt](https://github.com/taosdata/TDengine/tree/develop/examples/C%23/stmt)                                       | 使用 TDengine.Connector 实现的参数绑定的示例 |
| [schemaless](https://github.com/taosdata/TDengine/tree/develop/examples/C%23/schemaless)                           | 使用 TDengine.Connector 实现的使用 schemaless 写入的示例 |
| [benchmark](https://github.com/taosdata/TDengine/tree/develop/examples/C%23/taosdemo)                              | 使用 TDengine.Connector 实现的简易 Benchmark |
| [async   query](https://github.com/taosdata/TDengine/blob/develop/src/connector/C%23/examples/QueryAsyncSample.cs) | 使用 TDengine.Connector 实现的异步查询的示例 |
| [subscribe](https://github.com/taosdata/TDengine/blob/develop/src/connector/C%23/examples/SubscribeSample.cs)      | 使用 TDengine.Connector 实现的订阅数据的示例 |

## 重要更新记录

| TDengine.Connector | 说明                           |
|--------------------|--------------------------------|
|        1.0.2       | 新增连接管理、同步查询、错误信息等功能。   |
|        1.0.3       | 新增参数绑定、schemaless、 json tag等功能。 |
|        1.0.4       | 新增异步查询，订阅等功能。修复绑定参数 bug。    |
|        1.0.5       | 修复 Windows 同步查询中文报错 bug。   |
|        1.0.6       | 修复 schemaless 在 1.0.4 和 1.0.5 中失效 bug。 |

## 其他说明

### 第三方驱动

Maikebing.Data.Taos 是一个 TDengine 的 ADO.NET 连接器，支持 Linux，Windows 平台。该连接器由社区贡献者`麦壳饼@@maikebing` 提供，具体请参考:

* 接口下载:<https://github.com/maikebing/Maikebing.EntityFrameworkCore.Taos>
* 用法说明:<https://www.taosdata.com/blog/2020/11/02/1901.html>

## 常见问题

* "Unable to establish connection"，"Unable to resolve FQDN"

一般是因为 FQDN 配置不正确。可以参考[如何彻底搞懂 TDengine 的 FQDN](https://www.taosdata.com/blog/2021/07/29/2741.html)解决。

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