<!--

    Licensed to the Apache Software Foundation (ASF) under one
    or more contributor license agreements.  See the NOTICE file
    distributed with this work for additional information
    regarding copyright ownership.  The ASF licenses this file
    to you under the Apache License, Version 2.0 (the
    "License"); you may not use this file except in compliance
    with the License.  You may obtain a copy of the License at
    
        http://www.apache.org/licenses/LICENSE-2.0
    
    Unless required by applicable law or agreed to in writing,
    software distributed under the License is distributed on an
    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
    KIND, either express or implied.  See the License for the
    specific language governing permissions and limitations
    under the License.

-->

# C# 原生接口

## 1. 环境要求

* .NET SDK >= 5.0 或 .NET Framework 4.x
* Thrift >= 0.14.1
* NLog >= 4.7.9

## 2. 依赖安装

您可以使用 NuGet Package Manager, .NET CLI等工具来安装，以 .NET CLI为例

如果您使用的是.NET 5.0 或者更高版本的SDK，输入如下命令即可安装最新的NuGet包

```Bash
dotnet add package Apache.IoTDB
```

如果您想安装更早版本的客户端，只需要指定版本即可

```Bash
# 安装0.12.1.2版本的客户端
dotnet add package Apache.IoTDB --version 0.12.1.2
```
注意：请勿使用高版本客户端连接低版本服务。

## 3. 快速入门

```C#
// 参数定义
string host = "localhost";
int port = 6667;
int pool_size = 2;

// 初始化session
var session_pool = new SessionPool(host, port, pool_size);

// 开启session
await session_pool.Open(false);

// 创建时间序列
await session_pool.CreateTimeSeries("root.test_group.test_device.ts1", TSDataType.TEXT, TSEncoding.PLAIN, Compressor.UNCOMPRESSED);
await session_pool.CreateTimeSeries("root.test_group.test_device.ts2", TSDataType.BOOLEAN, TSEncoding.PLAIN, Compressor.UNCOMPRESSED);
await session_pool.CreateTimeSeries("root.test_group.test_device.ts3", TSDataType.INT32, TSEncoding.PLAIN, Compressor.UNCOMPRESSED);

// 插入record
var measures = new List<string>{"ts1", "ts2", "ts3"};
var values = new List<object> { "test_text", true, (int)123 };
var timestamp = 1;
var rowRecord = new RowRecord(timestamp, values, measures);
await session_pool.InsertRecordAsync("root.test_group.test_device", rowRecord);

// 插入Tablet
var timestamp_lst = new List<long>{ timestamp + 1 };
var value_lst = new List<object> {"iotdb", true, (int) 12};
var tablet = new Tablet("root.test_group.test_device", measures, value_lst, timestamp_lst);
await session_pool.InsertTabletAsync(tablet);

// 关闭Session
await session_pool.Close();
```

## 4. 全量接口说明

SessionPool 连接池支持并发客户端请求，线程安全。当 `pool_size`设为 1 时，其行为等同于单个 session。推荐使用 SessionPool ，作为实现与数据库交互的核心接口，SessionPool 集成了丰富的方法，支持数据写入、查询以及元数据操作等功能，详细介绍见下文。

### 4.1 基础接口

| 方法名         | 参数                      | 描述         | 示例                           |
| ---------------- | --------------------------- | -------------- | -------------------------------- |
| Open           | bool                      | 打开会话     | session\_pool.Open(false)      |
| Close          | null                      | 关闭会话     | session\_pool.Close()          |
| IsOpen         | null                      | 查看会话状态 | session\_pool.IsOpen()         |
| OpenDebugMode  | LoggingConfiguration=null | 启用调试模式 | session\_pool.OpenDebugMode()  |
| CloseDebugMode | null                      | 禁用调试模式 | session\_pool.CloseDebugMode() |
| SetTimeZone    | string                    | 设置时区     | session\_pool.GetTimeZone()    |
| GetTimeZone    | null                      | 获取时区     | session\_pool.GetTimeZone()    |

### 4.2 元数据接口

| 方法名                     | 参数                                                                 | 描述                 | 示例                                                                                                      |
| ---------------------------- | ---------------------------------------------------------------------- | ---------------------- | ----------------------------------------------------------------------------------------------------------- |
| SetStorageGroup            | string                                                               | （创建）存储组       | session\_pool.SetStorageGroup("root.97209\_TEST\_CSHARP\_CLIENT\_GROUP\_01")                              |
| CreateTimeSeries           | string, TSDataType, TSEncoding, Compressor                           | 创建时间序列         | session\_pool.InsertTabletsAsync(tablets)                                                                 |
| CreateMultiTimeSeriesAsync | List, List , List , List | 创建多个时间序列     | session\_pool.CreateMultiTimeSeriesAsync(ts\_path\_lst, data\_type\_lst, encoding\_lst, compressor\_lst); |
| CheckTimeSeriesExistsAsync | string                                                               | 查看时间序列是否存在 | session\_pool.CheckTimeSeriesExistsAsync(time series)                                                     |

### 4.3 写入接口

C# 原生接口支持通过 Record 和 Tablet 两种方式进行数据写入：

* RowRecord 是对 IoTDB 中的`record`数据进行封装和抽象，适合单行数据写入的场景，其构造方法如下

```C#
var rowRecord = 
  new RowRecord(long timestamps, List<object> values, List<string> measurements);
```

* Tablet 是一种类似于表格的数据结构，适合一个设备若干行非空数据块写入的场景，其构造方法如下

```C#
var tablet = 
  new Tablet(string deviceId,  List<string> measurements, List<List<object>> values, List<long> timestamps);
```

#### 4.3.1 Record

| 方法名                              | 参数                          | 描述                   | 示例                                                                                                                                         |
| ------------------------------------- | ------------------------------- | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| InsertRecordAsync                   | string, RowRecord             | 插入单条记录           | session\_pool.InsertRecordAsync("root.97209\_TEST\_CSHARP\_CLIENT\_GROUP.TEST\_CSHARP\_CLIENT\_DEVICE", new RowRecord(1, values, measures)); |
| InsertRecordsAsync                  | List, List | 插入多条记录           | session\_pool.InsertRecordsAsync(device\_id, rowRecords)                                                                                     |
| InsertRecordsOfOneDeviceAsync       | string, List       | 插入同一设备的记录     | session\_pool.InsertRecordsOfOneDeviceAsync(device\_id, rowRecords)                                                                          |
| InsertRecordsOfOneDeviceSortedAsync | string, List       | 插入同一设备的有序记录 | session\_pool.InsertRecordsOfOneDeviceSortedAsync(deviceId, sortedRowRecords);                                                               |
| TestInsertRecordAsync               | string, RowRecord             | 测试插入记录           | session\_pool.TestInsertRecordAsync("root.97209\_TEST\_CSHARP\_CLIENT\_GROUP.TEST\_CSHARP\_CLIENT\_DEVICE", rowRecord)                       |
| TestInsertRecordsAsync              | List, List | 测试插入记录           | session\_pool.TestInsertRecordsAsync(device\_id, rowRecords)                                                                                 |

#### 4.3.2 Tablet

| 方法名                 | 参数         | 描述             | 示例                                          |
| ------------------------ | -------------- | ------------------ | ----------------------------------------------- |
| InsertTabletAsync      | Tablet       | 插入单个 tablet  | session\_pool.InsertTabletAsync(tablet)       |
| InsertTabletsAsync     | List | 插入一批 tablets | session\_pool.InsertTabletsAsync(tablets)     |
| TestInsertTabletAsync  | Tablet       | 测试插入 tablet  | session\_pool.TestInsertTabletAsync(tablet)   |
| TestInsertTabletsAsync | List | 测试插入 tablets | session\_pool.TestInsertTabletsAsync(tablets) |

### 4.4 查询接口

| 方法名                         | 参数   | 描述                | 示例                                                                                                                                                                               |
| -------------------------------- | -------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| ExecuteQueryStatementAsync     | string | 执行 SQL 查询语句   | session\_pool.ExecuteQueryStatementAsync("select \* from root.97209\_TEST\_CSHARP\_CLIENT\_GROUP.TEST\_CSHARP\_CLIENT\_DEVICE where time<15");                                     |
| ExecuteNonQueryStatementAsync| string | 执行 SQL 非查询语句 | session\_pool.ExecuteNonQueryStatementAsync( "create timeseries root.97209\_TEST\_CSHARP\_CLIENT\_GROUP.TEST\_CSHARP\_CLIENT\_DEVICE.status with datatype=BOOLEAN,encoding=PLAIN") |

### 4.5 删除接口

| 方法名                   | 参数                     | 描述           | 示例                                                                                 |
| -------------------------- | -------------------------- | ---------------- | -------------------------------------------------------------------------------------- |
| DeleteStorageGroupAsync  | string                   | 删除单个存储组 | session\_pool.DeleteStorageGroupAsync("root.97209\_TEST\_CSHARP\_CLIENT\_GROUP\_01") |
| DeleteStorageGroupsAsync | List             | 删除存储组     | session\_pool.DeleteStorageGroupAsync("root.97209\_TEST\_CSHARP\_CLIENT\_GROUP")     |
| DeleteTimeSeriesAsync    | List             | 删除时间序列   | session\_pool.DeleteTimeSeriesAsync(ts\_path\_lst)                                   |
| DeleteTimeSeriesAsync    | string                   | 删除时间序列   | session\_pool.DeleteTimeSeriesAsync(ts\_path)                                        |
| DeleteDataAsync          | List, long, long | 删除数据       | session\_pool.DeleteDataAsync(ts\_path\_lst, 2, 3)                                   |

## 5. 示例代码

完整示例请参考：[Apache.IoTDB.Samples](https://github.com/apache/iotdb-client-csharp/tree/main/samples/Apache.IoTDB.Samples)