Merge pull request #102 from taosdata/docs/xftan/readme

docs: update readme
taosdata · Feb 5, 2025 · 09a7271 · 09a7271
2 parents 6320d1e + 7cd3bd6
commit 09a7271
Show file tree

Hide file tree

Showing 3 changed files with 86 additions and 127 deletions.
diff --git a/.github/workflows/linux.yml → .github/workflows/build.yml b/.github/workflows/linux.yml → .github/workflows/build.yml
diff --git a/README-CN.md b/README-CN.md
@@ -2,9 +2,17 @@
 # TDengine C# Connector
 <!-- omit in toc -->
 
-| Github Action Tests                                                                          | CodeCov                                                                                                                                                   |
-|----------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------|
-| ![actions](https://github.com/taosdata/taos-connector-dotnet/actions/workflows/linux.yml/badge.svg) | [![codecov](https://codecov.io/gh/taosdata/taos-connector-dotnet/graph/badge.svg?token=U30JZYDGMS)](https://codecov.io/gh/taosdata/taos-connector-dotnet) |
+[![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/taosdata/taos-connector-dotnet/build.yml)](https://github.com/taosdata/taos-connector-dotnet/actions/workflows/build.yml)
+[![codecov](https://codecov.io/gh/taosdata/taos-connector-dotnet/graph/badge.svg?token=U30JZYDGMS)](https://codecov.io/gh/taosdata/taos-connector-dotnet)
+![GitHub commit activity](https://img.shields.io/github/commit-activity/m/taosdata/taos-connector-dotnet)
+![GitHub License](https://img.shields.io/github/license/taosdata/taos-connector-dotnet)
+![NuGet Version](https://img.shields.io/nuget/v/TDengine.Connector)
+<br />
+[![Twitter Follow](https://img.shields.io/twitter/follow/tdenginedb?label=TDengine&style=social)](https://twitter.com/tdenginedb)
+[![YouTube Channel](https://img.shields.io/badge/Subscribe_@tdengine--white?logo=youtube&style=social)](https://www.youtube.com/@tdengine)
+[![Discord Community](https://img.shields.io/badge/Join_Discord--white?logo=discord&style=social)](https://discord.com/invite/VZdSuUg4pS)
+[![LinkedIn](https://img.shields.io/badge/Follow_LinkedIn--white?logo=linkedin&style=social)](https://www.linkedin.com/company/tdengine)
+[![StackOverflow](https://img.shields.io/badge/Ask_StackOverflow--white?logo=stackoverflow&style=social&logoColor=orange)](https://stackoverflow.com/questions/tagged/tdengine)
 
 [English](README.md) | 简体中文
 
@@ -13,17 +21,14 @@
 <!-- omit in toc -->
 
 - [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-性能测试)
+- [2. 文档](#2-文档)
+- [3. 前置条件](#3-前置条件)
+- [4. 构建](#4-构建)
+- [5. 测试](#5-测试)
+  - [5.1 运行测试](#51-运行测试)
+  - [5.2 添加用例](#52-添加用例)
+  - [5.3 性能测试](#53-性能测试)
+- [6. CI/CD](#6-cicd)
 - [7. 提交 Issue](#7-提交-issue)
 - [8. 提交 PR](#8-提交-pr)
 - [9. 引用](#9-引用)
@@ -33,72 +38,45 @@
 
 `TDengine.Connector` 是 TDengine 提供的 C# 语言连接器。C# 开发人员可以通过它开发存取 TDengine 集群数据的 C# 应用软件。
 
-### 1.1 连接方式
+## 2. 文档
 
-- 原生连接：通过客户端驱动程序 taosc 直接与服务端程序 taosd 建立连接。这种方式需要保证客户端的驱动程序 taosc 和服务端的 taosd 版本保持一致。
-- Websocket 连接： 通过 taosAdapter 组件提供的 WebSocket API 建立与 taosd 的连接，不依赖 TDengine 客户端驱动。
+- 使用 C# Connector, 请参考 [开发指南](https://docs.taosdata.com/develop/)，包含了应用如何引入 `TDengine.Connector` 和数据写入、查询、无模式写入、参数绑定和数据订阅等示例。
+- 其他参考信息请看 [参考手册](https://docs.taosdata.com/reference/connector/csharp/)，包含了版本历史、数据类型、示例程序汇总、API 说明和常见问题等。
+- 本README主要是为想自己贡献、编译、测试 C# Connector的开发者写的。如果要学习 TDengine，可以浏览 [官方文档](https://docs.taosdata.com/)。
 
-我们推荐使用 WebSocket 连接方式。 详细说明请参考：[连接方式](https://docs.taosdata.com/develop/connect/#%E8%BF%9E%E6%8E%A5%E6%96%B9%E5%BC%8F) 。
+## 3. 前置条件
 
-### 1.2 dotnet 版本兼容性
+- 安装 [.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)
 
-- .NET Framework 4.6 及以上版本。
-- .NET 5.0 及以上版本。
-
-### 1.3 支持的平台
-
-- 原生连接支持的平台和 TDengine 客户端驱动支持的平台一致。
-- WebSocket 连接支持所有能运行 .NET 运行时的平台。
-
-## 2. 获取驱动
-
-可以在当前 .NET 项目的路径下，通过 dotnet CLI 添加 Nuget package `TDengine.Connector` 到当前项目。
-
-``` bash
-dotnet add package TDengine.Connector
-```
-
-也可以修改当前项目的 `.csproj` 文件，添加如下 ItemGroup。
-
-``` XML
-  <ItemGroup>
-    <PackageReference Include="TDengine.Connector" Version="3.1.*" />
-  </ItemGroup>
-```
-
-## 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)
-
-## 5. 构建
+## 4. 构建
 
 1. `dotnet restore` 还原项目依赖。
 2. `dotnet build --no-restore` 构建项目。
 
-## 6. 测试
+## 5. 测试
 
-### 6.1 运行测试
+### 5.1 运行测试
 
 1. 执行测试前确保已经安装 TDengine 服务端，并且已经启动 taosd 与 taosAdapter，数据库干净无数据。
 2. 项目目录下执行 `dotnet test` 运行测试，测试会连接到本地的 TDengine 服务器与 taosAdapter 进行测试。
 3. 测试成功会打印 `Test Run Successful`，测试失败会打印失败信息 `Test Run Failed`。
 
-### 6.2 添加用例
+### 5.2 添加用例
 
 在 `test` 目录下添加测试用例，ADO.NET 的测试用例添加到 `test/Data.Tests`，客户端驱动的测试用例添加到 `test/Driver.Test/Client`。
 用例使用 xunit 框架。
 
-### 6.3 性能测试
+### 5.3 性能测试
 
 性能测试还在开发中。
 
+## 6. CI/CD
+
+- [Build Workflow](https://github.com/taosdata/taos-connector-dotnet/actions/workflows/build.yml)
+- [Code Coverage](https://app.codecov.io/gh/taosdata/taos-connector-dotnet)
+
 ## 7. 提交 Issue
 
 我们欢迎提交 [GitHub Issue](https://github.com/taosdata/taos-connector-dotnet/issues/new?template=Blank+issue)。 提交时请说明下面信息：
@@ -118,7 +96,8 @@ dotnet add package TDengine.Connector
 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 查看覆盖率。
+6. 提交 PR 后，可以通过 [Pull Request](https://github.com/taosdata/taos-connector-dotnet/pulls) 找到自己的 PR，点击对应链接进去可以看到自己 PR CI 是否通过，如果通过会显示 “All checks have passed”。无论 CI 是否通过，都可以点击 “Show all checks” -> “Details” 来查看详细用例日志。
+7. 提交 PR 后，如果 CI 通过，可以在 [codecov](https://app.codecov.io/gh/taosdata/taos-connector-dotnet/pulls) 页面找到自己 PR 查看覆盖率。
 
 ## 9. 引用
 

diff --git a/README.md b/README.md
@@ -2,9 +2,17 @@
 # TDengine C# Connector
 <!-- omit in toc -->
 
-| Github Action Tests                                                                                 | CodeCov                                                                                                                                                   |
-|-----------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------|
-| ![actions](https://github.com/taosdata/taos-connector-dotnet/actions/workflows/linux.yml/badge.svg) | [![codecov](https://codecov.io/gh/taosdata/taos-connector-dotnet/graph/badge.svg?token=U30JZYDGMS)](https://codecov.io/gh/taosdata/taos-connector-dotnet) |
+[![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/taosdata/taos-connector-dotnet/build.yml)](https://github.com/taosdata/taos-connector-dotnet/actions/workflows/build.yml)
+[![codecov](https://codecov.io/gh/taosdata/taos-connector-dotnet/graph/badge.svg?token=U30JZYDGMS)](https://codecov.io/gh/taosdata/taos-connector-dotnet)
+![GitHub commit activity](https://img.shields.io/github/commit-activity/m/taosdata/taos-connector-dotnet)
+![GitHub License](https://img.shields.io/github/license/taosdata/taos-connector-dotnet)
+![NuGet Version](https://img.shields.io/nuget/v/TDengine.Connector)
+<br />
+[![Twitter Follow](https://img.shields.io/twitter/follow/tdenginedb?label=TDengine&style=social)](https://twitter.com/tdenginedb)
+[![YouTube Channel](https://img.shields.io/badge/Subscribe_@tdengine--white?logo=youtube&style=social)](https://www.youtube.com/@tdengine)
+[![Discord Community](https://img.shields.io/badge/Join_Discord--white?logo=discord&style=social)](https://discord.com/invite/VZdSuUg4pS)
+[![LinkedIn](https://img.shields.io/badge/Follow_LinkedIn--white?logo=linkedin&style=social)](https://www.linkedin.com/company/tdengine)
+[![StackOverflow](https://img.shields.io/badge/Ask_StackOverflow--white?logo=stackoverflow&style=social&logoColor=orange)](https://stackoverflow.com/questions/tagged/tdengine)
 
 English | [简体中文](README-CN.md)
 
@@ -13,86 +21,49 @@ English | [简体中文](README-CN.md)
 <!-- omit in toc -->
 
 - [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)
+- [2. Documentation](#2-documentation)
+- [3. Prerequisites](#3-prerequisites)
+- [4. Build](#4-build)
+- [5. Testing](#5-testing)
+    - [5.1 Test Execution](#51-test-execution)
+    - [5.2 Test Case Addition](#52-test-case-addition)
+    - [5.3 Performance Testing](#53-performance-testing)
+- [6. CI/CD](#6-cicd)
 - [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.
 
-### 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.
-
-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
-
-### 1.3 Supported Platforms
-
-- 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
+## 2. Documentation
 
-Nuget package `TDengine.Connector` can be added to the current project through dotnet CLI under the path of the current .NET project.
+- To use C# connector, please check [Developer Guide](https://docs.tdengine.com/developer-guide/), which includes how an
+  application can introduce the `TDengine.Connector`, as well as examples of data writing, querying, schemaless writing,
+  parameter binding, and data subscription.
+- For other reference information, please
+  check [Reference Manual](https://docs.tdengine.com/tdengine-reference/client-libraries/csharp/), which includes
+  version history, data types, example programs, API descriptions, and FAQs.
+- This quick guide is mainly for developers who like to contribute/build/test the C# connector by themselves. To learn
+  about TDengine, you can visit the [official documentation](https://docs.tdengine.com).
 
-```bash
-dotnet add package TDengine.Connector
-```
+## 3. Prerequisites
 
-You can also modify the `.csproj` file of the current project and add the following ItemGroup.
-
-``` XML
-   <ItemGroup>
-     <PackageReference Include="TDengine.Connector" Version="3.1.*" />
-   </ItemGroup>
-```
-
-## 3. Documentation
-
-- 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.
-
-## 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
+- 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)
 
-## 5. Build
+## 4. Build
 
 1. `dotnet restore` Restore the project's dependencies.
 2. `dotnet build --no-restore` Build the project.
 
-## 6. Testing
+## 5. Testing
 
-### 6.1 Test Execution
+### 5.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.
@@ -101,16 +72,21 @@ You can also modify the `.csproj` file of the current project and add the follow
 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
+### 5.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
+### 5.3 Performance Testing
 
 Performance testing is in progress.
 
+## 6. CI/CD
+
+- [Build Workflow](https://github.com/taosdata/taos-connector-dotnet/actions/workflows/build.yml)
+- [Code Coverage](https://app.codecov.io/gh/taosdata/taos-connector-dotnet)
+
 ## 7. Submitting Issues
 
 We welcome the submission
@@ -133,7 +109,11 @@ We welcome developers to contribute to this project. Please follow the steps bel
 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
+6. After submitting the PR, you can find your PR through
+   the [Pull Request](https://github.com/taosdata/taos-connector-dotnet/pulls). Click on the corresponding link to see
+   if the CI for your PR has passed. If it has passed, it will display "All checks have passed". Regardless of whether
+   the CI passes or not, you can click "Show all checks" -> "Details" to view the detailed test case logs.
+7. 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.
 
 ## 9. References