docs(diver):C# add docs with WebSocket (taosdata#16950)

* docs(diver):C# add docs with WebSocket * docs(driver):C# docs update with commnets
flyingangel2013 · Sep 20, 2022 · 78ac5ee · 78ac5ee
1 parent b08520d
commit 78ac5ee
Show file tree

Hide file tree

Showing 11 changed files with 430 additions and 8 deletions.
diff --git a/docs/examples/csharp/.gitignore b/docs/examples/csharp/.gitignore
@@ -1,4 +1,12 @@
 bin
 obj
 .vs
-*.sln
+*.sln
+wsConnect/obj
+wsInsert/obj
+wsQuery/obj
+wsStmt/obj
+wsConnect/bin
+wsInsert/bin
+wsQuery/bin
+wsStmt/bin
diff --git a/docs/examples/csharp/wsConnect/Program.cs b/docs/examples/csharp/wsConnect/Program.cs
@@ -0,0 +1,25 @@
+using System;
+using TDengineWS.Impl;
+
+namespace Examples
+{
+    public class WSConnExample
+    {
+        static void Main(string[] args)
+        {
+            string DSN = "ws://root:taosdata@127.0.0.1:6041/test";
+            IntPtr wsConn = LibTaosWS.WSConnectWithDSN(DSN);
+            if (wsConn == IntPtr.Zero)
+            {
+                throw new Exception($"get WS connection failed,reason:{LibTaosWS.WSErrorStr(IntPtr.Zero)} code:{LibTaosWS.WSErrorNo(IntPtr.Zero)}");
+            }
+            else
+            {
+                Console.WriteLine("Establish connect success.");
+            }
+
+            // close connection.
+            LibTaosWS.WSClose(wsConn);
+        }
+    }
+}
diff --git a/docs/examples/csharp/wsConnect/wsConnect.csproj b/docs/examples/csharp/wsConnect/wsConnect.csproj
@@ -0,0 +1,13 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net5.0</TargetFramework>
+    <Nullable>enable</Nullable>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="TDengine.Connector" Version="3.0.1" />
+  </ItemGroup>
+
+</Project>
diff --git a/docs/examples/csharp/wsInsert/Program.cs b/docs/examples/csharp/wsInsert/Program.cs
@@ -0,0 +1,58 @@
+using System;
+using TDengineWS.Impl;
+
+namespace Examples
+{
+    public class WSInsertExample
+    {
+        static void Main(string[] args)
+        {
+            string DSN = "ws://root:taosdata@127.0.0.1:6041/test";
+            IntPtr wsConn = LibTaosWS.WSConnectWithDSN(DSN);
+
+            // Assert if connection is validate
+            if (wsConn == IntPtr.Zero)
+            {
+                throw new Exception($"get WS connection failed,reason:{LibTaosWS.WSErrorStr(IntPtr.Zero)} code:{LibTaosWS.WSErrorNo(IntPtr.Zero)}");
+            }
+            else
+            {
+                Console.WriteLine("Establish connect success.");
+            }
+
+            string createTable = "CREATE STABLE test.meters (ts timestamp, current float, voltage int, phase float) TAGS (location binary(64), groupId int);";
+            string insert = "INSERT INTO test.d1001 USING test.meters TAGS('California.SanFrancisco', 2) VALUES ('2018-10-03 14:38:05.000', 10.30000, 219, 0.31000) ('2018-10-03 14:38:15.000', 12.60000, 218, 0.33000) ('2018-10-03 14:38:16.800', 12.30000, 221, 0.31000)" +
+                            "test.d1002 USING test.meters TAGS('California.SanFrancisco', 3) VALUES('2018-10-03 14:38:16.650', 10.30000, 218, 0.25000)" +
+                            "test.d1003 USING test.meters TAGS('California.LosAngeles', 2) VALUES('2018-10-03 14:38:05.500', 11.80000, 221, 0.28000)('2018-10-03 14:38:16.600', 13.40000, 223, 0.29000) " +
+                            "test.d1004 USING test.meters TAGS('California.LosAngeles', 3) VALUES('2018-10-03 14:38:05.000', 10.80000, 223, 0.29000)('2018-10-03 14:38:06.500', 11.50000, 221, 0.35000)";
+
+            IntPtr wsRes = LibTaosWS.WSQuery(wsConn, createTable);
+            ValidInsert("create table", wsRes);
+            LibTaosWS.WSFreeResult(wsRes);
+
+            wsRes = LibTaosWS.WSQuery(wsConn, insert);
+            ValidInsert("insert data", wsRes);
+            LibTaosWS.WSFreeResult(wsRes);
+
+            // close connection.
+            LibTaosWS.WSClose(wsConn);
+        }
+
+        static void ValidInsert(string desc, IntPtr wsRes)
+        {
+            int code = LibTaosWS.WSErrorNo(wsRes);
+            if (code != 0)
+            {
+                throw new Exception($"execute SQL failed: reason: {LibTaosWS.WSErrorStr(wsRes)}, code:{code}");
+            }
+            else
+            {
+                Console.WriteLine("{0} success affect {2} rows, cost {1} nanoseconds", desc, LibTaosWS.WSTakeTiming(wsRes),LibTaosWS.WSAffectRows(wsRes));
+            }
+        }
+    }
+
+}
+// Establish connect success.
+// create table success affect 0 rows, cost 3717542 nanoseconds
+// insert data success affect 8 rows, cost 2613637 nanoseconds
diff --git a/docs/examples/csharp/wsInsert/wsInsert.csproj b/docs/examples/csharp/wsInsert/wsInsert.csproj
@@ -0,0 +1,13 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net5.0</TargetFramework>
+    <Nullable>enable</Nullable>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="TDengine.Connector" Version="3.0.1" />
+  </ItemGroup>
+
+</Project>
diff --git a/docs/examples/csharp/wsQuery/Program.cs b/docs/examples/csharp/wsQuery/Program.cs
@@ -0,0 +1,74 @@
+using System;
+using TDengineWS.Impl;
+using System.Collections.Generic;
+using TDengineDriver;
+
+namespace Examples
+{
+    public class WSQueryExample
+    {
+        static void Main(string[] args)
+        {
+            string DSN = "ws://root:taosdata@127.0.0.1:6041/test";
+            IntPtr wsConn = LibTaosWS.WSConnectWithDSN(DSN);
+            if (wsConn == IntPtr.Zero)
+            {
+                throw new Exception($"get WS connection failed,reason:{LibTaosWS.WSErrorStr(IntPtr.Zero)} code:{LibTaosWS.WSErrorNo(IntPtr.Zero)}");
+            }
+            else
+            {
+                Console.WriteLine("Establish connect success.");
+            }
+
+            string select = "select * from test.meters";
+
+            // optional:wsRes = LibTaosWS.WSQuery(wsConn, select);
+            IntPtr wsRes = LibTaosWS.WSQueryTimeout(wsConn, select, 1);
+            // Assert if query execute success.
+            int code = LibTaosWS.WSErrorNo(wsRes);
+            if (code != 0)
+            {
+                throw new Exception($"execute SQL failed: reason: {LibTaosWS.WSErrorStr(wsRes)}, code:{code}");
+            }
+
+            // get meta data
+            List<TDengineMeta> metas = LibTaosWS.WSGetFields(wsRes);
+            // get retrieved data
+            List<object> dataSet = LibTaosWS.WSGetData(wsRes);
+
+            // do something with result.
+            foreach (var meta in metas)
+            {
+                Console.Write("{0} {1}({2}) \t|\t", meta.name, meta.TypeName(), meta.size);
+            }
+            Console.WriteLine("");
+
+            for (int i = 0; i < dataSet.Count;)
+            {
+                for (int j = 0; j < metas.Count; j++)
+                {
+                    Console.Write("{0}\t|\t", dataSet[i]);
+                    i++;
+                }
+                Console.WriteLine("");
+            }
+
+            // Free result after use.
+            LibTaosWS.WSFreeResult(wsRes);
+
+            // close connection.
+            LibTaosWS.WSClose(wsConn);
+        }
+    }
+}
+
+// Establish connect success.
+// ts TIMESTAMP(8)         |       current FLOAT(4)        |       voltage INT(4)  |       phase FLOAT(4)  |       location BINARY(64)     |       groupid INT(4)  |
+// 1538548685000   |       10.8    |       223     |       0.29    |       California.LosAngeles   |       3       |
+// 1538548686500   |       11.5    |       221     |       0.35    |       California.LosAngeles   |       3       |
+// 1538548685500   |       11.8    |       221     |       0.28    |       California.LosAngeles   |       2       |
+// 1538548696600   |       13.4    |       223     |       0.29    |       California.LosAngeles   |       2       |
+// 1538548685000   |       10.3    |       219     |       0.31    |       California.SanFrancisco |       2       |
+// 1538548695000   |       12.6    |       218     |       0.33    |       California.SanFrancisco |       2       |
+// 1538548696800   |       12.3    |       221     |       0.31    |       California.SanFrancisco |       2       |
+// 1538548696650   |       10.3    |       218     |       0.25    |       California.SanFrancisco |       3       |
diff --git a/docs/examples/csharp/wsQuery/wsQuery.csproj b/docs/examples/csharp/wsQuery/wsQuery.csproj
@@ -0,0 +1,13 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net5.0</TargetFramework>
+    <Nullable>enable</Nullable>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="TDengine.Connector" Version="3.0.1" />
+  </ItemGroup>
+
+</Project>
diff --git a/docs/examples/csharp/wsStmt/Program.cs b/docs/examples/csharp/wsStmt/Program.cs
@@ -0,0 +1,95 @@
+using System;
+using TDengineWS.Impl;
+using TDengineDriver;
+using System.Runtime.InteropServices;
+
+namespace Examples
+{
+    public class WSStmtExample
+    {
+        static void Main(string[] args)
+        {
+            const string DSN = "ws://root:taosdata@127.0.0.1:6041/test";
+            const string table = "meters";
+            const string database = "test";
+            const string childTable = "d1005";
+            string insert = $"insert into ? using {database}.{table} tags(?,?) values(?,?,?,?)";
+            const int numOfTags = 2;
+            const int numOfColumns = 4;
+
+            // Establish connection
+            IntPtr wsConn = LibTaosWS.WSConnectWithDSN(DSN);
+            if (wsConn == IntPtr.Zero)
+            {
+                throw new Exception($"get WS connection failed,reason:{LibTaosWS.WSErrorStr(IntPtr.Zero)} code:{LibTaosWS.WSErrorNo(IntPtr.Zero)}");
+            }
+            else
+            {
+                Console.WriteLine("Establish connect success...");
+            }
+
+            // init stmt
+            IntPtr wsStmt = LibTaosWS.WSStmtInit(wsConn);
+            if (wsStmt != IntPtr.Zero)
+            {
+                int code = LibTaosWS.WSStmtPrepare(wsStmt, insert);
+                ValidStmtStep(code, wsStmt, "WSStmtPrepare");
+
+                TAOS_MULTI_BIND[] wsTags = new TAOS_MULTI_BIND[] { WSMultiBind.WSBindNchar(new string[] { "California.SanDiego" }), WSMultiBind.WSBindInt(new int?[] { 4 }) };
+                code = LibTaosWS.WSStmtSetTbnameTags(wsStmt, $"{database}.{childTable}", wsTags, numOfTags);
+                ValidStmtStep(code, wsStmt, "WSStmtSetTbnameTags");
+
+                TAOS_MULTI_BIND[] data = new TAOS_MULTI_BIND[4];
+                data[0] = WSMultiBind.WSBindTimestamp(new long[] { 1538548687000, 1538548688000, 1538548689000, 1538548690000, 1538548691000 });
+                data[1] = WSMultiBind.WSBindFloat(new float?[] { 10.30F, 10.40F, 10.50F, 10.60F, 10.70F });
+                data[2] = WSMultiBind.WSBindInt(new int?[] { 223, 221, 222, 220, 219 });
+                data[3] = WSMultiBind.WSBindFloat(new float?[] { 0.31F, 0.32F, 0.33F, 0.35F, 0.28F });
+                code = LibTaosWS.WSStmtBindParamBatch(wsStmt, data, numOfColumns);
+                ValidStmtStep(code, wsStmt, "WSStmtBindParamBatch");
+
+                code = LibTaosWS.WSStmtAddBatch(wsStmt);
+                ValidStmtStep(code, wsStmt, "WSStmtAddBatch");
+
+                IntPtr stmtAffectRowPtr = Marshal.AllocHGlobal(Marshal.SizeOf(typeof(Int32)));
+                code = LibTaosWS.WSStmtExecute(wsStmt, stmtAffectRowPtr);
+                ValidStmtStep(code, wsStmt, "WSStmtExecute");
+                Console.WriteLine("WS STMT insert {0} rows...", Marshal.ReadInt32(stmtAffectRowPtr));
+                Marshal.FreeHGlobal(stmtAffectRowPtr);
+
+                LibTaosWS.WSStmtClose(wsStmt);
+
+                // Free unmanaged memory
+                WSMultiBind.WSFreeTaosBind(wsTags);
+                WSMultiBind.WSFreeTaosBind(data);
+
+                //check result with SQL "SELECT * FROM test.d1005;"
+            }
+            else
+            {
+                throw new Exception("Init STMT failed...");
+            }
+
+            // close connection.
+            LibTaosWS.WSClose(wsConn);
+        }
+
+        static void ValidStmtStep(int code, IntPtr wsStmt, string desc)
+        {
+            if (code != 0)
+            {
+                throw new Exception($"{desc} failed,reason: {LibTaosWS.WSErrorStr(wsStmt)}, code: {code}");
+            }
+            else
+            {
+                Console.WriteLine("{0} success...", desc);
+            }
+        }
+    }
+}
+
+// WSStmtPrepare success...
+// WSStmtSetTbnameTags success...
+// WSStmtBindParamBatch success...
+// WSStmtAddBatch success...
+// WSStmtExecute success...
+// WS STMT insert 5 rows...
diff --git a/docs/examples/csharp/wsStmt/wsStmt.csproj b/docs/examples/csharp/wsStmt/wsStmt.csproj
@@ -0,0 +1,13 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net5.0</TargetFramework>
+    <Nullable>enable</Nullable>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="TDengine.Connector" Version="3.0.1" />
+  </ItemGroup>
+
+</Project>
diff --git a/docs/zh/07-develop/01-connect/_connect_cs.mdx b/docs/zh/07-develop/01-connect/_connect_cs.mdx
@@ -2,7 +2,7 @@
 {{#include docs/examples/csharp/ConnectExample.cs}}
 ```
 
-:::info
-C# 连接器目前只支持原生连接。
+```csharp title="WebSocket 连接"
+{{#include docs/examples/csharp/wsConnect/Program.cs}}
+```
 
-:::