--- 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` 提供，具体请参考: * 接口下载: * 用法说明: ## 常见问题 * "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)