From 752ebc174565bd61c6f6b86331fd50cc45422f2c Mon Sep 17 00:00:00 2001 From: t_max <1172915550@qq.com> Date: Fri, 24 Jan 2025 17:36:59 +0800 Subject: [PATCH] docs: update readme --- README-CN.md | 99 +++++++++++++++++++++++++++++++++++++--------- README.md | 110 ++++++++++++++++++++++++++++++++++++++++++--------- 2 files changed, 171 insertions(+), 38 deletions(-) diff --git a/README-CN.md b/README-CN.md index 804699d..b9d0ae4 100644 --- a/README-CN.md +++ b/README-CN.md @@ -1,4 +1,6 @@ -# 简介 + +# TDengine C# Connector + | Github Action Tests | CodeCov | |----------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------| @@ -6,19 +8,49 @@ [English](README.md) | 简体中文 + +## 目录 + + +- [1. 简介](#1-简介) + - [1.1 连接方式](#11-连接方式) + - [1.2 dotnet 版本兼容性](#12-dotnet-版本兼容性) + - [1.3 支持的平台](#13-支持的平台) +- [2. 获取驱动](#2-获取驱动) +- [3. 文档](#3-文档) +- [4. 前置条件](#4-前置条件) +- [5. 构建](#5-构建) +- [6. 测试](#6-测试) + - [6.1 运行测试](#61-运行测试) + - [6.2 添加用例](#62-添加用例) + - [6.3 性能测试](#63-性能测试) +- [7. 提交 Issue](#7-提交-issue) +- [8. 提交 PR](#8-提交-pr) +- [9. 引用](#9-引用) +- [10. 许可证](#10-许可证) + +## 1. 简介 + `TDengine.Connector` 是 TDengine 提供的 C# 语言连接器。C# 开发人员可以通过它开发存取 TDengine 集群数据的 C# 应用软件。 -`TDengine.Connector` 提供了两种连接方式： +### 1.1 连接方式 - 原生连接：通过客户端驱动程序 taosc 直接与服务端程序 taosd 建立连接。这种方式需要保证客户端的驱动程序 taosc 和服务端的 taosd 版本保持一致。 - Websocket 连接： 通过 taosAdapter 组件提供的 WebSocket API 建立与 taosd 的连接，不依赖 TDengine 客户端驱动。 -## 支持的平台 +我们推荐使用 WebSocket 连接方式。 详细说明请参考：[连接方式](https://docs.taosdata.com/develop/connect/#%E8%BF%9E%E6%8E%A5%E6%96%B9%E5%BC%8F) 。 + +### 1.2 dotnet 版本兼容性 + +- .NET Framework 4.6 及以上版本。 +- .NET 5.0 及以上版本。 + +### 1.3 支持的平台 - 原生连接支持的平台和 TDengine 客户端驱动支持的平台一致。 - WebSocket 连接支持所有能运行 .NET 运行时的平台。 -# 获取驱动 +## 2. 获取驱动 可以在当前 .NET 项目的路径下，通过 dotnet CLI 添加 Nuget package `TDengine.Connector` 到当前项目。 @@ -34,36 +66,65 @@ dotnet add package TDengine.Connector ``` -# 文档 - -- 开发示例请见[开发指南](https://docs.taosdata.com/develop/) -- 版本历史、TDengine 对应版本以及 API 说明请见[参考手册](https://docs.taosdata.com/reference/connector/csharp/) +## 3. 文档 -# 贡献 +- 开发示例请见 [开发指南](https://docs.taosdata.com/develop/)，包含了数据写入、查询、无模式写入、参数绑定和数据订阅等示例。 +- 其他参考信息请见 [参考手册](https://docs.taosdata.com/reference/connector/csharp/)，包含了版本历史、TDengine 对应版本以及 API 说明和常见问题等。 -鼓励每个人帮助改进这个项目，以下是这个项目的开发测试流程： - -## 前置条件 +## 4. 前置条件 * 安装 [.NET SDK](https://dotnet.microsoft.com/download) * [Nuget 客户端](https://docs.microsoft.com/en-us/nuget/install-nuget-client-tools) （可选安装） -* 安装 TDengine 客户端驱动，具体步骤请参考[安装客户端驱动](https://docs.taosdata.com/develop/connect/#%E5%AE%89%E8%A3%85%E5%AE%A2%E6%88%B7%E7%AB%AF%E9%A9%B1%E5%8A%A8-taosc) +* 安装 TDengine 客户端驱动，具体步骤请参考 [安装客户端驱动](https://docs.taosdata.com/develop/connect/#%E5%AE%89%E8%A3%85%E5%AE%A2%E6%88%B7%E7%AB%AF%E9%A9%B1%E5%8A%A8-taosc) -## 构建 +## 5. 构建 1. `dotnet restore` 还原项目依赖。 2. `dotnet build --no-restore` 构建项目。 -## 测试 +## 6. 测试 + +### 6.1 运行测试 + +1. 执行测试前确保已经安装 TDengine 服务端，并且已经启动 taosd 与 taosAdapter，数据库干净无数据。 +2. 项目目录下执行 `dotnet test` 运行测试，测试会连接到本地的 TDengine 服务器与 taosAdapter 进行测试。 +3. 测试成功会打印 `Test Run Successful`，测试失败会打印失败信息 `Test Run Failed`。 + +### 6.2 添加用例 + +在 `test` 目录下添加测试用例，ADO.NET 的测试用例添加到 `test/Data.Tests`，客户端驱动的测试用例添加到 `test/Driver.Test/Client`。 +用例使用 xunit 框架。 + +### 6.3 性能测试 + +性能测试还在开发中。 + +## 7. 提交 Issue + +我们欢迎提交 [GitHub Issue](https://github.com/taosdata/taos-connector-dotnet/issues/new?template=Blank+issue)。 提交时请说明下面信息： + +- 问题描述，是否必现 +- 驱动版本 +- 连接参数（不需要服务器地址、用户名和密码） +- TDengine 版本 + +## 8. 提交 PR + +我们欢迎开发者一起开发本项目，提交 PR 时请参考下面步骤： -1. 执行测试前确保已经安装 TDengine 服务端，并且已经启动 taosd 与 taosAdapter，数据库干净无数据 -2. 项目目录下执行 `dotnet test` 运行测试，测试会连接到本地的 TDengine 服务器与 taosAdapter 进行测试 +1. Fork 本项目，请参考 ([how to fork a repo](https://docs.github.com/en/get-started/quickstart/fork-a-repo)) +2. 从 main 分支创建一个新分支，请使用有意义的分支名称 (`git checkout -b my_branch`)。 +3. 修改代码，保证所有单元测试通过，并增加新的单元测试验证修改。 +4. 提交修改到远端分支 (`git push origin my_branch`)。 +5. 在 GitHub 上创建一个 Pull + Request ([how to create a pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request))。 +6. 提交 PR 后，如果 CI 通过，可以在 [codecov](https://app.codecov.io/gh/taosdata/taos-connector-dotnet/pulls) 页面找到自己 PR 查看覆盖率。 -# 引用 +## 9. 引用 - [TDengine 官网](https://www.taosdata.com/) - [TDengine GitHub](https://github.com/taosdata/TDengine) -# 许可证 +## 10. 许可证 [MIT License](./LICENSE) \ No newline at end of file diff --git a/README.md b/README.md index 400bcdd..1d0fa4a 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,6 @@ -# Introduction + +# TDengine C# Connector + | Github Action Tests | CodeCov | |-----------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------| @@ -6,21 +8,53 @@ English | [简体中文](README-CN.md) + +## Table of Contents + + +- [1. Introduction](#1-introduction) + - [1.1 Connection Methods](#11-connection-methods) + - [1.2 .NET Version Compatibility](#12-net-version-compatibility) + - [1.3 Supported Platforms](#13-supported-platforms) +- [2. Get the Driver](#2-get-the-driver) +- [3. Documentation](#3-documentation) +- [4. Prerequisites](#4-prerequisites) +- [5. Build](#5-build) +- [6. Testing](#6-testing) + - [6.1 Test Execution](#61-test-execution) + - [6.2 Test Case Addition](#62-test-case-addition) + - [6.3 Performance Testing](#63-performance-testing) +- [7. Submitting Issues](#7-submitting-issues) +- [8. Submitting PRs](#8-submitting-prs) +- [9. References](#9-references) +- [10. License](#10-license) + + +## 1. Introduction + `TDengine.Connector` is the C# language connector provided by TDengine. C# developers can use it to develop C# application software that accesses TDengine cluster data. -`TDengine.Connector` provides two connection methods: +### 1.1 Connection Methods - Native Connection: Establishes a connection directly with the server program taosd through the client driver taosc. This method requires the client driver taosc and the server taosd to be of the same version. - WebSocket Connection: Establishes a connection with taosd through the WebSocket API provided by the taosAdapter component, without relying on the TDengine client driver. -## Supported Platforms +We recommend using the WebSocket connection method. For detailed instructions, please refer +to: [Connection Methods](https://docs.tdengine.com/developer-guide/connecting-to-tdengine/#connection-methods). + +### 1.2 .NET Version Compatibility + +- .NET Framework 4.6 and above +- .NET 5.0 and above -- Native Connection: Supported platforms are consistent with those supported by the TDengine client driver. -- WebSocket Connection: Supports all platforms that can run the .NET runtime. +### 1.3 Supported Platforms -# Get the Driver +- The platforms supported by the native connection are consistent with those supported by the TDengine client driver. +- WebSocket connections support all platforms that can run .NET. + +## 2. Get the Driver Nuget package `TDengine.Connector` can be added to the current project through dotnet CLI under the path of the current .NET project. @@ -36,40 +70,78 @@ You can also modify the `.csproj` file of the current project and add the follow ``` -# Documentation - -- For development examples, see the [Developer Guide](https://docs.tdengine.com/developer-guide/). -- For version history, TDengine version compatibility, and API documentation, see - the [Reference Manual](https://docs.tdengine.com/tdengine-reference/client-libraries/csharp/). +## 3. Documentation -# Contributing +- For development examples, see [Developer Guide](https://docs.tdengine.com/developer-guide/), which includes examples + of data writing, querying, schemaless writing, parameter binding, and data subscription. +- For other reference information, + see [Reference Manual](https://docs.tdengine.com/tdengine-reference/client-libraries/csharp/), which includes version + history, data types, example programs, API descriptions, and FAQs. -We encourage everyone to help improve this project. Below is the development and testing process for this project: - -## Prerequisites +## 4. Prerequisites * Install [.NET SDK](https://dotnet.microsoft.com/download) * [Nuget Client](https://docs.microsoft.com/en-us/nuget/install-nuget-client-tools) (optional installation) * Install the TDengine client driver. For specific steps, please refer to [Installing the client driver](https://docs.tdengine.com/develop/connect/#install-client-driver-taosc) -## Building +## 5. Build 1. `dotnet restore` Restore the project's dependencies. 2. `dotnet build --no-restore` Build the project. -## Testing +## 6. Testing + +### 6.1 Test Execution 1. Before running tests, ensure that the TDengine server is installed and that `taosd` and `taosAdapter` are running. The database should be empty. 2. In the project directory, run `dotnet test` to execute the tests. The tests will connect to the local TDengine server and taosAdapter for testing. +3. If the tests pass, `Test Run Successful` will be printed. If the tests fail, the failure information + `Test Run Failed` + will be printed. + +### 6.2 Test Case Addition + +Add test cases in the `test` directory. Add ADO.NET test cases to `test/Data.Tests` and client driver test cases to +`test/Driver.Test/Client`. +The test cases use the xunit framework. + +### 6.3 Performance Testing + +Performance testing is in progress. + +## 7. Submitting Issues + +We welcome the submission +of [GitHub Issue](https://github.com/taosdata/taos-connector-dotnet/issues/new?template=Blank+issue). When +submitting, please provide the following information: + +- Description of the issue and whether it is consistently reproducible +- Driver version +- Connection parameters (excluding server address, username, and password) +- TDengine version + +## 8. Submitting PRs + +We welcome developers to contribute to this project. Please follow the steps below to submit a PR: + +1. Fork this project. Please refer + to [how to fork a repo](https://docs.github.com/en/get-started/quickstart/fork-a-repo). +2. Create a new branch from the main branch with a meaningful branch name (`git checkout -b my_branch`). +3. Modify the code, ensure all unit tests pass, and add new unit tests to verify the changes. +4. Push the changes to the remote branch (`git push origin my_branch`). +5. Create a Pull Request on GitHub. Please refer + to [how to create a pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request). +6. After submitting the PR, if the CI passes, you can find your PR on + the [codecov](https://app.codecov.io/gh/taosdata/taos-connector-dotnet/pulls) page to check the coverage. -# References +## 9. References - [TDengine Official Website](https://tdengine.com/) - [TDengine GitHub](https://github.com/taosdata/TDengine) -# License +## 10. License [MIT License](./LICENSE) \ No newline at end of file