csharp.mdx 7.0 KB
Newer Older
B
Bo Ding 已提交
1
---
sangshuduo's avatar
sangshuduo 已提交
2
toc_max_heading_level: 4
B
Bo Ding 已提交
3 4
sidebar_position: 7
sidebar_label: C#
D
dingbo 已提交
5
title: C# Connector
B
Bo Ding 已提交
6 7
---

sangshuduo's avatar
sangshuduo 已提交
8
import Preparition from "./_preparition.mdx"
sangshuduo's avatar
sangshuduo 已提交
9 10 11 12 13 14
import CSInsert from "../../04-develop/03-insert-data/_cs_sql.mdx"
import CSInfluxLine from "../../04-develop/03-insert-data/_cs_line.mdx"
import CSOpenTSDBTelnet from "../../04-develop/03-insert-data/_cs_opts_telnet.mdx"
import CSOpenTSDBJson from "../../04-develop/03-insert-data/_cs_opts_json.mdx"
import CSQuery from "../../04-develop/04-query-data/_cs.mdx"
import CSAsyncQuery from "../../04-develop/04-query-data/_cs_async.mdx"
sangshuduo's avatar
sangshuduo 已提交
15

sangshuduo's avatar
sangshuduo 已提交
16
`TDengine.Connector` 是 TDengine 提供的 C# 语言连接器。C# 开发人员可以通过它开发存取 TDengine 集群数据的 C# 应用软件。连接器支持通过客户端驱动(taosc)建立本地连接 TDengine 集群,进行数据写入、查询、订阅、schemaless 数据写入、参数绑定接口数据写入等功能。
B
Bo Ding 已提交
17

sangshuduo's avatar
sangshuduo 已提交
18
`TDengine.Connector` 目前暂未提供 REST 连接方式,用户可以参考 [RESTful APIs](https://docs.taosdata.com//reference/restful-api/) 文档自行编写。
B
Bo Ding 已提交
19

sangshuduo's avatar
sangshuduo 已提交
20
本文介绍如何在 Windows 或 Linux 环境中安装 `TDengine.Connector`,并通过 `TDengine.Connector` 连接 TDengine 集群,进行数据写入、查询等基本操作。
B
Bo Ding 已提交
21

22
## 支持的平台
B
Bo Ding 已提交
23

sangshuduo's avatar
sangshuduo 已提交
24
请参考[支持的平台列表](/reference/connector#支持的平台)
B
Bo Ding 已提交
25

26
## 版本支持
B
Bo Ding 已提交
27

sangshuduo's avatar
sangshuduo 已提交
28
请参考[版本支持列表](/reference/connector#版本支持)
B
Bo Ding 已提交
29

sangshuduo's avatar
sangshuduo 已提交
30
## 支持的功能特性
31

32
1. 连接管理
sangshuduo's avatar
sangshuduo 已提交
33 34
2. 普通查询
3. 连续查询
35
4. 参数绑定
sangshuduo's avatar
sangshuduo 已提交
36 37
5. 订阅功能
6. Schemaless
B
Bo Ding 已提交
38

39
## 安装步骤
B
Bo Ding 已提交
40

sangshuduo's avatar
sangshuduo 已提交
41 42 43 44
### 安装前准备

* 安装 [.NET SDK](https://dotnet.microsoft.com/download)
 - (可选安装)[Nuget 客户端](https://docs.microsoft.com/en-us/nuget/install-nuget-client-tools)
B
Bo Ding 已提交
45

sangshuduo's avatar
sangshuduo 已提交
46
<Preparition />
47 48 49 50 51

### 使用 dotnet CLI 安装

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

sangshuduo's avatar
sangshuduo 已提交
52
可以在当前 .NET 项目的路径下,通过 dotnet 命令引用 Nuget 中发布的 `TDengine.Connector` 到当前项目。
53 54 55

``` bash
dotnet add package TDengine.Connector
B
Bo Ding 已提交
56 57
```

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

sangshuduo's avatar
sangshuduo 已提交
60
可以下载 TDengine 的源码,直接引用最新版本的 TDengine.Connector 库
61 62 63 64

```bash
git clone https://github.com/taosdata/TDengine.git
cd TDengine/src/connector/C#/src/
sangshuduo's avatar
sangshuduo 已提交
65
cp -r TDengineDriver/ myProject
66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104

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

```
B
Bo Ding 已提交
105

106
## 使用示例
B
Bo Ding 已提交
107

sangshuduo's avatar
sangshuduo 已提交
108 109
### 写入数据

sangshuduo's avatar
sangshuduo 已提交
110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127
#### SQL 写入

<CSInsert />

#### InfluxDB 行协议写入

<CSInfluxLine />

#### OpenTSDB Telnet 行协议写入

<CSOpenTSDBTelnet />

#### OpenTSDB JSON 行协议写入

<CSOpenTSDBJson />

### 查询数据

sangshuduo's avatar
sangshuduo 已提交
128 129
#### 同步查询

sangshuduo's avatar
sangshuduo 已提交
130 131
<CSQuery />

sangshuduo's avatar
sangshuduo 已提交
132
#### 异步查询
sangshuduo's avatar
sangshuduo 已提交
133 134 135

<CSAsyncQuery />

sangshuduo's avatar
sangshuduo 已提交
136
### 更多示例程序
sangshuduo's avatar
sangshuduo 已提交
137

138 139 140 141 142 143 144 145 146
|示例程序                                                                                                               | 示例程序描述                                       |
|--------------------------------------------------------------------------------------------------------------------|--------------------------------------------|
| [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 |
147 148
| [async   query](https://github.com/taosdata/taos-connector-dotnet/blob/develop/examples/QueryAsyncSample.cs) | 使用 TDengine.Connector 实现的异步查询的示例 |
| [subscribe](https://github.com/taosdata/taos-connector-dotnet/blob/develop/examples/SubscribeSample.cs)      | 使用 TDengine.Connector 实现的订阅数据的示例 |
B
Bo Ding 已提交
149

150
## 重要更新记录
B
Bo Ding 已提交
151

152 153 154 155 156 157 158
| 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。 |
B
Bo Ding 已提交
159

160
## 其他说明
B
Bo Ding 已提交
161

162
### 第三方驱动
B
Bo Ding 已提交
163

sangshuduo's avatar
sangshuduo 已提交
164
`Maikebing.Data.Taos` 是一个 TDengine 的 ADO.NET 连接器,支持 Linux,Windows 平台。该连接器由社区贡献者`麦壳饼@@maikebing` 提供,具体请参考:
B
Bo Ding 已提交
165

166 167
* 接口下载:<https://github.com/maikebing/Maikebing.EntityFrameworkCore.Taos>
* 用法说明:<https://www.taosdata.com/blog/2020/11/02/1901.html>
B
Bo Ding 已提交
168

169
## 常见问题
B
Bo Ding 已提交
170

171
* "Unable to establish connection","Unable to resolve FQDN"
B
Bo Ding 已提交
172

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

175
* Unhandled exception. System.DllNotFoundException: Unable to load DLL 'taos' or one of its dependencies: 找不到指定的模块。
B
Bo Ding 已提交
176

177
一般是因为程序没有找到依赖的客户端驱动。解决方法为: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` 即可。
sangshuduo's avatar
sangshuduo 已提交
178

179
## API 参考
sangshuduo's avatar
sangshuduo 已提交
180

181
[API 参考](https://docs.taosdata.com/api/connector-csharp/html/860d2ac1-dd52-39c9-e460-0829c4e5a40b.htm)