Add SessionPool.CheckHealthAsync connectivity probe (#63)

新增 SessionPool.CheckHealthAsync 连通性探针

IsOpen() is a lifecycle flag - it reports whether the caller has opened the pool
and not yet closed it. Because the client keeps no heartbeat, it stays true after
the server goes down, and users routinely mistake it for a health check, e.g.
`if (pool.IsOpen()) return;` in a lazy-open guard, which then never rebuilds the
pool. This adds the connectivity check that IsOpen() is mistaken for, without
changing IsOpen() itself.
IsOpen() 是生命周期标志,仅表示调用方是否已打开且尚未关闭连接池。由于客户端无心跳,
服务端断开后它仍为 true,用户普遍将其误当作健康检查(例如惰性打开守卫里的
`if (pool.IsOpen()) return;`),从而导致连接池永远不会被重建。本提交新增了
IsOpen() 被误认为具备的连通性检查能力,且不改变 IsOpen() 自身行为。

- Add SessionPool.CheckHealthAsync(CancellationToken), which issues one lightweight
  request on an idle pooled connection and returns a SessionPoolHealth snapshot
  carrying Status, AvailableClients, TotalPoolSize, FailedReconnections, Message
  and the underlying Error.
  新增 SessionPool.CheckHealthAsync(CancellationToken):在空闲连接上发送一次轻量请求,
  返回包含状态、可用连接数、池容量、重连失败次数、说明和底层异常的 SessionPoolHealth 快照。

- Add SessionPoolHealthStatus with four outcomes: NotOpen (no network call is made),
  Healthy, Degraded (open but no idle connection to probe with - a saturation signal,
  not a server verdict) and Unhealthy (a connection was available but the server did
  not answer).
  新增 SessionPoolHealthStatus 四种结果:NotOpen(不发起网络调用)、Healthy、
  Degraded(池已打开但无空闲连接可用于探测,表示饱和而非服务端故障)、
  Unhealthy(有可用连接但服务端未响应)。

- Add ConcurrentClientQueue.TryTake so the probe never blocks. A health endpoint
  must not queue behind application load, so when every client is busy the probe
  returns Degraded immediately instead of waiting.
  新增 ConcurrentClientQueue.TryTake 使探针永不阻塞:健康检查端点不应排在业务负载之后,
  因此所有连接繁忙时立即返回 Degraded 而不是等待。

- The borrowed connection is always returned to the pool and a failed probe does not
  close it, so the existing reconnect-on-use path is unchanged.
  借出的连接总会归还池中,探测失败也不会关闭它,因此既有的按需重连路径保持不变。

- Forward CheckHealthAsync from TableSessionPool with identical semantics.
  TableSessionPool 以相同语义转发 CheckHealthAsync。

- Add tests for the NotOpen path, non-blocking TryTake semantics and the health
  snapshot; document the API in docs/SessionPool_Exception_Handling.md and docs/API.md.
  补充 NotOpen 路径、TryTake 非阻塞语义与健康快照的测试;在相关文档中说明该 API。
7 files changed
tree: acc32d047cb708acf5ec6fb23ed1be1b767acf30
  1. .github/
  2. Apache-IoTDB-Client-CSharp-UserCase/
  3. docs/
  4. samples/
  5. src/
  6. tests/
  7. .asf.yaml
  8. .dockerignore
  9. .editorconfig
  10. .gitattributes
  11. .gitignore
  12. .licenserc.yaml
  13. .pre-commit-config.yaml
  14. Apache.IoTDB.sln
  15. docker-compose-2c2d.yml
  16. docker-compose.yml
  17. launchSettings.json
  18. LICENSE
  19. PUBLISH.md
  20. README.md
  21. README_ZH.md
README.md

English | 中文

Apache IoTDB Client for C#

E2E Tests License NuGet Version NuGet Downloads

Overview

This is the C# client of Apache IoTDB.

Apache IoTDB (Internet of Things Database) is a data management system for time series data, which can provide users specific services, such as, data collection, storage and analysis. Due to its light weight structure, high performance and usable features together with its seamless integration with the Hadoop and Spark ecology, IoTDB meets the requirements of massive dataset storage, high throughput data input, and complex data analysis in the industrial IoT field.

Apache IoTDB website: https://iotdb.apache.org Apache IoTDB Github: https://github.com/apache/iotdb

Installation

Install from NuGet Package

We have prepared a Nuget Package for C# users. Users can directly install the Apache IoTDB client using the .NET CLI. To install, simply run the following command in your command line:

dotnet add package Apache.IoTDB

For more details, visit the package on NuGet.

[!NOTE] The Apache.IoTDB package only supports versions greater than .net framework 4.6.1.

Prerequisites

.NET SDK Version >= 5.0 
.NET Framework >= 4.6.1

How to Use the Client (Quick Start)

Users can quickly get started by referring to the use cases under the Apache-IoTDB-Client-CSharp-UserCase directory. These use cases serve as a useful resource for getting familiar with the client's functionality and capabilities.

For those who wish to delve deeper into the client's usage and explore more advanced features, the samples directory contains additional code samples.

Developer environment requirements for iotdb-client-csharp

.NET SDK Version >= 5.0
.NET Framework >= 4.6.1
ApacheThrift >= 0.14.1
NLog >= 4.7.9

OS

  • Linux, MacOS or other Unix-like OS
  • Windows + Bash (WSL, cygwin, Git Bash)

Command Line Tools

  • dotnet CLI
  • Thrift

Code Formatting

This project uses dotnet format to enforce consistent code style based on the .editorconfig rules.

Check formatting locally

dotnet format --verify-no-changes

Auto-fix formatting issues

dotnet format

The CI pipeline will automatically check code formatting on all pull requests. Please ensure your code is properly formatted before submitting a PR.

Publish your own client on nuget.org

You can find out how to publish from this doc.