[WIP]docs(driver):update C# webscoket to import dll from nupkg (#17485)

* docs(driver):update C# webscoket to import dll from nupkg * docs(driver):update description about C# using WebSocket dll from nuget package * docs(driver):update C# webscoket to import dll from nupkg 2nd * fix: typos Co-authored-by: Shuduo Sang <sangshuduo@gmail.com>
2023-01-17 12:07:01 +08:00 · 2023-01-17 12:07:01 +08:00 · 830086e756
parent 1af5aa6786
commit 830086e756
15 changed files with 98 additions and 48 deletions
--- a/docs/en/14-reference/03-connector/09-csharp.mdx
+++ b/docs/en/14-reference/03-connector/09-csharp.mdx
@ -17,7 +17,7 @@ import CSAsyncQuery from "../../07-develop/04-query-data/_cs_async.mdx"

 `TDengine.Connector` is a C# language connector provided by TDengine that allows C# developers to develop C# applications that access TDengine cluster data.

-The `TDengine.Connector` connector supports connect to TDengine instances via the TDengine client driver (taosc), providing data writing, querying, subscription, schemaless writing, bind interface, etc.The `TDengine.Connector` also supports WebSocket and developers can build connection through DSN, which supports data writing, querying, and parameter binding, etc.
+The `TDengine.Connector` connector supports connect to TDengine instances via the TDengine client driver (taosc), providing data writing, querying, subscription, schemaless writing, bind interface, etc.The `TDengine.Connector` also supports WebSocket from v3.0.1 and developers can build connection through DSN, which supports data writing, querying, and parameter binding, etc.

 This article describes how to install `TDengine.Connector` in a Linux or Windows environment and connect to TDengine clusters via `TDengine.Connector` to perform basic operations such as data writing and querying.

@ -66,31 +66,43 @@ Please refer to [version support list](/reference/connector#version-support)
 * [Nuget Client](https://docs.microsoft.com/en-us/nuget/install-nuget-client-tools) (optional installation)
 * Install TDengine client driver, please refer to [Install client driver](/reference/connector/#install-client-driver) for details

-### Install via dotnet CLI
+### Install `TDengine.Connector`

 <Tabs defaultValue="CLI">
-<TabItem value="CLI" label="Get C# driver using dotnet CLI">
+<TabItem value="CLI" label="Native Connection">

-You can reference the `TDengine.Connector` published in Nuget to the current project via the `dotnet` command under the path of the existing .NET project.
+You can reference the `TDengine.Connector` published in Nuget to the current project via the `dotnet` CLI under the path of the existing .NET project.

 ``` bash
 dotnet add package TDengine.Connector
 ```

-</TabItem>
-<TabItem value="source" label="Use source code to get C# driver">
+You may also modify the current.NET project file. You can include the following 'ItemGroup' in your project file (.csproj).

-You can [download the source code](https://github.com/taosdata/taos-connector-dotnet/tree/3.0) and directly reference the latest version of the TDengine.Connector library.
-
-```bash
-git clone -b 3.0 https://github.com/taosdata/taos-connector-dotnet.git
-cd taos-connector-dotnet
-cp -r src/ myProject
-
-cd myProject
-dotnet add exmaple.csproj reference src/TDengine.csproj
+``` XML
+  <ItemGroup>
+    <PackageReference Include="TDengine.Connector" Version="3.0.*" />
+  </ItemGroup>
 ```

+</TabItem>
+<TabItem value="source" label="WebSocket Connection">
+
+In this scenario, modifying your project file is required in order to copy the WebSocket dependency dynamic library from the nuget package into your project.
+```XML
+  <ItemGroup>
+    <PackageReference Include="TDengine.Connector" Version="3.0.*" GeneratePathProperty="true" />
+  </ItemGroup>
+  <Target Name="copyDLLDepency" BeforeTargets="BeforeBuild">
+    <ItemGroup>
+      <DepDLLFiles Include="$(PkgTDengine_Connector)\runtimes\**\*.*" />
+    </ItemGroup>
+    <Copy SourceFiles="@(DepDLLFiles)" DestinationFolder="$(OutDir)" />
+  </Target>
+```
+
+Notice: `TDengine.Connector` only version>= 3.0.2 includes the dynamic library for WebSocket.
+
 </TabItem>
 </Tabs>

@ -265,6 +277,7 @@ ws://localhost:6041/test

 | TDengine.Connector | Description |
 |--------------------|--------------------------------|
+|        3.0.2       | Support .NET Framework 4.5 and above. Support .Net standard 2.0. Nuget package includes dynamic library for WebSocket.|
 |        3.0.1       | Support WebSocket and Cloud，With function query, insert, and parameter binding|
 |        3.0.0       | Supports TDengine 3.0.0.0. TDengine 2.x is not supported. Added `TDengine.Impl.GetData()` interface to deserialize query results. |
 |        1.0.7       | Fixed TDengine.Query() memory leak. |
--- a/docs/examples/csharp/asyncQuery/asyncquery.csproj
+++ b/docs/examples/csharp/asyncQuery/asyncquery.csproj
@ -9,7 +9,7 @@
  </PropertyGroup>

  <ItemGroup>
-    <PackageReference Include="TDengine.Connector" Version="3.0.1" />
+    <PackageReference Include="TDengine.Connector" Version="3.0.*" />
  </ItemGroup>

 </Project>
--- a/docs/examples/csharp/connect/connect.csproj
+++ b/docs/examples/csharp/connect/connect.csproj
@ -9,7 +9,7 @@
  </PropertyGroup>

  <ItemGroup>
-    <PackageReference Include="TDengine.Connector" Version="3.0.0" />
+    <PackageReference Include="TDengine.Connector" Version="3.0.*" />
  </ItemGroup>

 </Project>
--- a/docs/examples/csharp/influxdbLine/influxdbline.csproj
+++ b/docs/examples/csharp/influxdbLine/influxdbline.csproj
@ -9,7 +9,7 @@
  </PropertyGroup>

  <ItemGroup>
-    <PackageReference Include="TDengine.Connector" Version="3.0.0" />
+    <PackageReference Include="TDengine.Connector" Version="3.0.*" />
  </ItemGroup>

 </Project>
--- a/docs/examples/csharp/optsJSON/optsJSON.csproj
+++ b/docs/examples/csharp/optsJSON/optsJSON.csproj
@ -9,7 +9,7 @@
  </PropertyGroup>

  <ItemGroup>
-    <PackageReference Include="TDengine.Connector" Version="3.0.0" />
+    <PackageReference Include="TDengine.Connector" Version="3.0.*" />
  </ItemGroup>

 </Project>
--- a/docs/examples/csharp/optsTelnet/optstelnet.csproj
+++ b/docs/examples/csharp/optsTelnet/optstelnet.csproj
@ -9,7 +9,7 @@
  </PropertyGroup>

  <ItemGroup>
-    <PackageReference Include="TDengine.Connector" Version="3.0.0" />
+    <PackageReference Include="TDengine.Connector" Version="3.0.*" />
  </ItemGroup>

 </Project>
--- a/docs/examples/csharp/query/query.csproj
+++ b/docs/examples/csharp/query/query.csproj
@ -9,7 +9,7 @@
  </PropertyGroup>

  <ItemGroup>
-    <PackageReference Include="TDengine.Connector" Version="3.0.1" />
+    <PackageReference Include="TDengine.Connector" Version="3.0.*" />
  </ItemGroup>

 </Project>
--- a/docs/examples/csharp/sqlInsert/sqlinsert.csproj
+++ b/docs/examples/csharp/sqlInsert/sqlinsert.csproj
@ -9,7 +9,7 @@
  </PropertyGroup>

  <ItemGroup>
-    <PackageReference Include="TDengine.Connector" Version="3.0.0" />
+    <PackageReference Include="TDengine.Connector" Version="3.0.*" />
  </ItemGroup>

 </Project>
--- a/docs/examples/csharp/stmtInsert/stmtinsert.csproj
+++ b/docs/examples/csharp/stmtInsert/stmtinsert.csproj
@ -9,7 +9,7 @@
  </PropertyGroup>

  <ItemGroup>
-    <PackageReference Include="TDengine.Connector" Version="3.0.0" />
+    <PackageReference Include="TDengine.Connector" Version="3.0.*" />
  </ItemGroup>

 </Project>
--- a/docs/examples/csharp/subscribe/subscribe.csproj
+++ b/docs/examples/csharp/subscribe/subscribe.csproj
@ -9,7 +9,7 @@
  </PropertyGroup>

  <ItemGroup>
-    <PackageReference Include="TDengine.Connector" Version="3.0.1" />
+    <PackageReference Include="TDengine.Connector" Version="3.0.*" />
  </ItemGroup>

 </Project>
--- a/docs/examples/csharp/wsConnect/wsConnect.csproj
+++ b/docs/examples/csharp/wsConnect/wsConnect.csproj
@ -3,11 +3,16 @@
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net5.0</TargetFramework>
-    <Nullable>enable</Nullable>
  </PropertyGroup>

  <ItemGroup>
-    <PackageReference Include="TDengine.Connector" Version="3.0.1" />
+    <PackageReference Include="TDengine.Connector" Version="3.0.*" GeneratePathProperty="true" />
  </ItemGroup>
+  <Target Name="copyDLLDependency" BeforeTargets="BeforeBuild">
+    <ItemGroup>
+      <DepDLLFiles Include="$(PkgTDengine_Connector)\runtimes\**\*.*" />
+    </ItemGroup>
+    <Copy SourceFiles="@(DepDLLFiles)" DestinationFolder="$(OutDir)" />
+  </Target>

 </Project>
--- a/docs/examples/csharp/wsInsert/wsInsert.csproj
+++ b/docs/examples/csharp/wsInsert/wsInsert.csproj
@ -5,9 +5,13 @@
    <TargetFramework>net5.0</TargetFramework>
    <Nullable>enable</Nullable>
  </PropertyGroup>
-
  <ItemGroup>
-    <PackageReference Include="TDengine.Connector" Version="3.0.1" />
+    <PackageReference Include="TDengine.Connector" Version="3.0.*" GeneratePathProperty="true" />
  </ItemGroup>
-
+  <Target Name="copyDLLDependency" BeforeTargets="BeforeBuild">
+    <ItemGroup>
+      <DepDLLFiles Include="$(PkgTDengine_Connector)\runtimes\**\*.*" />
+    </ItemGroup>
+    <Copy SourceFiles="@(DepDLLFiles)" DestinationFolder="$(OutDir)" />
+  </Target>
 </Project>
--- a/docs/examples/csharp/wsQuery/wsQuery.csproj
+++ b/docs/examples/csharp/wsQuery/wsQuery.csproj
@ -7,7 +7,13 @@
  </PropertyGroup>

  <ItemGroup>
-    <PackageReference Include="TDengine.Connector" Version="3.0.1" />
+    <PackageReference Include="TDengine.Connector" Version="3.0.*" GeneratePathProperty="true" />
  </ItemGroup>
+  <Target Name="copyDLLDependency" BeforeTargets="BeforeBuild">
+    <ItemGroup>
+      <DepDLLFiles Include="$(PkgTDengine_Connector)\runtimes\**\*.*" />
+    </ItemGroup>
+    <Copy SourceFiles="@(DepDLLFiles)" DestinationFolder="$(OutDir)" />
+  </Target>

 </Project>
--- a/docs/examples/csharp/wsStmt/wsStmt.csproj
+++ b/docs/examples/csharp/wsStmt/wsStmt.csproj
@ -7,7 +7,13 @@
  </PropertyGroup>

  <ItemGroup>
-    <PackageReference Include="TDengine.Connector" Version="3.0.1" />
+    <PackageReference Include="TDengine.Connector" Version="3.0.*" GeneratePathProperty="true" />
  </ItemGroup>
+  <Target Name="copyDLLDependency" BeforeTargets="BeforeBuild">
+    <ItemGroup>
+      <DepDLLFiles Include="$(PkgTDengine_Connector)\runtimes\**\*.*" />
+    </ItemGroup>
+    <Copy SourceFiles="@(DepDLLFiles)" DestinationFolder="$(OutDir)" />
+  </Target>

 </Project>
--- a/docs/zh/08-connector/40-csharp.mdx
+++ b/docs/zh/08-connector/40-csharp.mdx
@ -17,7 +17,7 @@ import CSAsyncQuery from "../07-develop/04-query-data/_cs_async.mdx"

 `TDengine.Connector` 是 TDengine 提供的 C# 语言连接器。C# 开发人员可以通过它开发存取 TDengine 集群数据的 C# 应用软件。

-`TDengine.Connector` 连接器支持通过 TDengine 客户端驱动（taosc）建立与 TDengine 运行实例的连接，提供数据写入、查询、数据订阅、schemaless 数据写入、参数绑定接口数据写入等功能。 `TDengine.Connector` 还支持 WebSocket，通过 DSN 建立 WebSocket 连接，提供数据写入、查询、参数绑定接口数据写入等功能。
+`TDengine.Connector` 连接器支持通过 TDengine 客户端驱动（taosc）建立与 TDengine 运行实例的连接，提供数据写入、查询、数据订阅、schemaless 数据写入、参数绑定接口数据写入等功能。 `TDengine.Connector` 自 v3.0.1 起还支持 WebSocket，通过 DSN 建立 WebSocket 连接，提供数据写入、查询、参数绑定接口数据写入等功能。

 本文介绍如何在 Linux 或 Windows 环境中安装 `TDengine.Connector`，并通过 `TDengine.Connector` 连接 TDengine 集群，进行数据写入、查询等基本操作。

@ -67,30 +67,45 @@ import CSAsyncQuery from "../07-develop/04-query-data/_cs_async.mdx"
 * [Nuget 客户端](https://docs.microsoft.com/en-us/nuget/install-nuget-client-tools) （可选安装）
 * 安装 TDengine 客户端驱动，具体步骤请参考[安装客户端驱动](../#安装客户端驱动)

-### 使用 dotnet CLI 安装
+### 安装 TDengine.Connector

 <Tabs defaultValue="CLI">
-<TabItem value="CLI" label="使用 dotnet CLI 获取 C# 驱动">
+<TabItem value="CLI" label="使用本地连接">

-可以在当前 .NET 项目的路径下，通过 dotnet 命令引用 Nuget 中发布的 `TDengine.Connector` 到当前项目。
+可以在当前 .NET 项目的路径下，通过 dotnet CLI 添加 Nuget package `TDengine.Connector` 到当前项目。

 ``` bash
 dotnet add package TDengine.Connector
 ```

-</TabItem>
-<TabItem value="source" label="使用源码获取 C# 驱动">
+也可以修改当前项目的 `.csproj` 文件，添加如下 ItemGroup。

-也可以[下载源码](https://github.com/taosdata/taos-connector-dotnet/tree/3.0)，直接引用 TDengine.Connector 库
-
-```bash
-git clone -b 3.0 https://github.com/taosdata/taos-connector-dotnet.git
-cd taos-connector-dotnet
-cp -r src/ myProject
-
-cd myProject
-dotnet add exmaple.csproj reference src/TDengine.csproj
+``` XML
+  <ItemGroup>
+    <PackageReference Include="TDengine.Connector" Version="3.0.*" />
+  </ItemGroup>
 ```
+
+</TabItem>
+
+<TabItem value="source" label="使用 WebSocket 连接">
+
+需要修改目标项目的 `.csproj` 项目文件，将 `.nupkg` 中的 `runtimes` 目录中的动态库复制到当前项目的 `$(OutDir)` 目录下。
+
+```XML
+  <ItemGroup>
+    <PackageReference Include="TDengine.Connector" Version="3.0.*" GeneratePathProperty="true" />
+  </ItemGroup>
+  <Target Name="copyDLLDepency" BeforeTargets="BeforeBuild">
+    <ItemGroup>
+      <DepDLLFiles Include="$(PkgTDengine_Connector)\runtimes\**\*.*" />
+    </ItemGroup>
+    <Copy SourceFiles="@(DepDLLFiles)" DestinationFolder="$(OutDir)" />
+  </Target>
+```
+
+注意：`TDengine.Connector` 自 version>= 3.0.2 的 nuget package 中才会有动态库（ taosws.dll，libtaows.so ）。
+
 </TabItem>
 </Tabs>

@ -148,9 +163,9 @@ namespace TDengineExample

 各部分意义见下表：

-* **protocol**: 显示指定以何种方式建立连接，例如：`ws://localhost:6041` 指定以 Websocket 方式建立连接(支持http/ws)。
+* **protocol**: 显示指定以何种方式建立连接，例如：`ws://localhost:6041` 指定以 Websocket 方式建立连接（支持 http/ws ）。
  
-* **username/password**: 用于创建连接的用户名及密码（默认`root/taosdata`）。
+* **username/password**: 用于创建连接的用户名及密码（默认 `root/taosdata` ）。
  
 * **host/port**: 指定创建连接的服务器及端口，WebSocket 连接默认为 `localhost:6041` 。
  
@ -266,6 +281,7 @@ namespace TDengineExample

 | TDengine.Connector | 说明                           |
 |--------------------|--------------------------------|
+|        3.0.2       | 支持 .NET Framework 4.5 及以上，支持 .NET standard 2.0。Nuget Package 包含 WebSocket 动态库。 |
 |        3.0.1       | 支持 WebSocket 和 Cloud，查询，插入，参数绑定。 |
 |        3.0.0       | 支持 TDengine 3.0.0.0，不兼容 2.x。新增接口TDengine.Impl.GetData()，解析查询结果。 |
 |        1.0.7       | 修复 TDengine.Query()内存泄露。 |