diff --git a/docs/en/15-programming/01-connect/06-csharp.md b/docs/en/15-programming/01-connect/06-csharp.md new file mode 100644 index 0000000000000000000000000000000000000000..948415c740f6b79507e86ad1332320f2ec341604 --- /dev/null +++ b/docs/en/15-programming/01-connect/06-csharp.md @@ -0,0 +1,78 @@ +--- +sidebar_label: C# +title: Connect with C# Connector +description: Connect to TDengine cloud service using C# connector +--- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +## Create Project + +```bash +dotnet new console -o example +``` + +## Add C# TDengine Driver class lib + +```bash +cd example +dotnet add package TDengine.Connector +``` + +## Config + +Run this command in your terminal to save TDengine cloud token as variables: + + + + +```bash +export TDENGINE_CLOUD_DSN="" +``` + + + + +```bash +set TDENGINE_CLOUD_DSN="" +``` + + + + +```powershell +$env:TDENGINE_CLOUD_DSN="" +``` + + + + + + +:::note +Replace with real TDengine cloud DSN. To obtain the real value, please log in [TDengine Cloud](https://cloud.tdengine.com) and click "Connector" and then select "C#". + +::: + + +## Connect + +``` XML + + + + Exe + net5.0 + enable + + + + + + + +``` + +```C# +{{#include docs/examples/csharp/cloud-example/Connect.cs}} +``` diff --git a/docs/en/15-programming/06-connector/06-csharp.md b/docs/en/15-programming/06-connector/06-csharp.md new file mode 100644 index 0000000000000000000000000000000000000000..b745a9c970321020caec8b9482376c82980cb422 --- /dev/null +++ b/docs/en/15-programming/06-connector/06-csharp.md @@ -0,0 +1,101 @@ +--- +sidebar_label: C# +title: TDengine C# Connector +description: Detailed guide for C# Connector +--- + + `TDengine.Connector` is the official C# connector for TDengine. C# developers can develop applications to access TDengine instance data. + +The source code for `TDengine.Connector` is hosted on [GitHub](https://github.com/taosdata/taos-connector-dotnet/tree/3.0). + +## Installation + +### Pre-installation + +Install the .NET deployment SDK. + +### Add TDengine.Connector through Nuget + +```bash +dotnet add package TDengine.Connector +``` + +## Establishing a connection + +``` XML + + + + Exe + net5.0 + enable + + + + + + + +``` + +``` C# +{{#include docs/examples/csharp/cloud-example/connect/Program.cs}} +``` + +## Usage examples + +### Basic Insert and Query + +``` XML + + + + Exe + net5.0 + enable + + + + + + + + +``` + +```C# +{{#include docs/examples/csharp/cloud-example/usage/Program.cs}} +``` + +### STMT Insert + +``` XML + + + + Exe + net5 + enable + + + + + + + + +``` + +```C# +{{#include docs/examples/csharp/cloud-example/stmt/Program.cs}} +``` + +## Important Updates + +| TDengine.Connector | Description | +| ------------------------- | ---------------------------------------------------------------- | +| 3.0.1 | Support connect to TDengine cloud service + +## API Reference + +[API Reference](https://docs.taosdata.com/api/connector-csharp/html/860d2ac1-dd52-39c9-e460-0829c4e5a40b.htm) diff --git a/docs/examples/csharp/.gitignore b/docs/examples/csharp/.gitignore index b3aff79f3706e23aa74199a7f521f7912d2b0e45..627e2d891bb373f27bf77455c8cc12f7bd9eac37 100644 --- a/docs/examples/csharp/.gitignore +++ b/docs/examples/csharp/.gitignore @@ -1,4 +1,7 @@ -bin -obj -.vs -*.sln \ No newline at end of file +cloud-example/connect/bin +cloud-example/connect/obj +cloud-example/usage/bin +cloud-example/usage/obj +cloud-example/stmt/bin +cloud-example/stmt/obj +.vs \ No newline at end of file diff --git a/docs/examples/csharp/cloud-example/cloud-example.sln b/docs/examples/csharp/cloud-example/cloud-example.sln new file mode 100644 index 0000000000000000000000000000000000000000..a870f4e60217f62f534a5a6c9f22f763cc0dc247 --- /dev/null +++ b/docs/examples/csharp/cloud-example/cloud-example.sln @@ -0,0 +1,34 @@ + +Microsoft Visual Studio Solution File, Format Version 12.00 +# Visual Studio Version 16 +VisualStudioVersion = 16.0.30114.105 +MinimumVisualStudioVersion = 10.0.40219.1 +Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "connect", "connect\connect.csproj", "{4006CF0C-17BE-4508-9682-A85298F8C92D}" +EndProject +Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "usage", "usage\usage.csproj", "{243C420F-FC47-4F21-B81E-83CDE91F2D47}" +EndProject +Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "stmt", "stmt\stmt.csproj", "{B6907CB6-41CB-4644-AEE1-551456EADE12}" +EndProject +Global + GlobalSection(SolutionConfigurationPlatforms) = preSolution + Debug|Any CPU = Debug|Any CPU + Release|Any CPU = Release|Any CPU + EndGlobalSection + GlobalSection(SolutionProperties) = preSolution + HideSolutionNode = FALSE + EndGlobalSection + GlobalSection(ProjectConfigurationPlatforms) = postSolution + {4006CF0C-17BE-4508-9682-A85298F8C92D}.Debug|Any CPU.ActiveCfg = Debug|Any CPU + {4006CF0C-17BE-4508-9682-A85298F8C92D}.Debug|Any CPU.Build.0 = Debug|Any CPU + {4006CF0C-17BE-4508-9682-A85298F8C92D}.Release|Any CPU.ActiveCfg = Release|Any CPU + {4006CF0C-17BE-4508-9682-A85298F8C92D}.Release|Any CPU.Build.0 = Release|Any CPU + {243C420F-FC47-4F21-B81E-83CDE91F2D47}.Debug|Any CPU.ActiveCfg = Debug|Any CPU + {243C420F-FC47-4F21-B81E-83CDE91F2D47}.Debug|Any CPU.Build.0 = Debug|Any CPU + {243C420F-FC47-4F21-B81E-83CDE91F2D47}.Release|Any CPU.ActiveCfg = Release|Any CPU + {243C420F-FC47-4F21-B81E-83CDE91F2D47}.Release|Any CPU.Build.0 = Release|Any CPU + {B6907CB6-41CB-4644-AEE1-551456EADE12}.Debug|Any CPU.ActiveCfg = Debug|Any CPU + {B6907CB6-41CB-4644-AEE1-551456EADE12}.Debug|Any CPU.Build.0 = Debug|Any CPU + {B6907CB6-41CB-4644-AEE1-551456EADE12}.Release|Any CPU.ActiveCfg = Release|Any CPU + {B6907CB6-41CB-4644-AEE1-551456EADE12}.Release|Any CPU.Build.0 = Release|Any CPU + EndGlobalSection +EndGlobal diff --git a/docs/examples/csharp/cloud-example/connect/Program.cs b/docs/examples/csharp/cloud-example/connect/Program.cs new file mode 100644 index 0000000000000000000000000000000000000000..df6ee3b7755c1ae0b2d127d8ed87c310229e046d --- /dev/null +++ b/docs/examples/csharp/cloud-example/connect/Program.cs @@ -0,0 +1,34 @@ +using System; +using TDengineWS.Impl; + +namespace Cloud.Examples +{ + public class ConnectExample + { + static void Main(string[] args) + { + string dsn = Environment.GetEnvironmentVariable("TDENGINE_CLOUD_DSN"); + Connect(dsn); + } + + public static void Connect(string dsn) + { + // get connect + IntPtr conn = LibTaosWS.WSConnectWithDSN(dsn); + if (conn == IntPtr.Zero) + { + throw new Exception($"get connection failed,reason:{LibTaosWS.WSErrorStr(conn)},code:{LibTaosWS.WSErrorNo(conn)}"); + } + else + { + Console.WriteLine("Establish connect success."); + } + + // do something ... + + // close connect + LibTaosWS.WSClose(conn); + + } + } +} \ No newline at end of file diff --git a/docs/examples/csharp/cloud-example/connect/connect.csproj b/docs/examples/csharp/cloud-example/connect/connect.csproj new file mode 100644 index 0000000000000000000000000000000000000000..2a4903745b0d93a8bc5f39a27ef3d1b52e6001a2 --- /dev/null +++ b/docs/examples/csharp/cloud-example/connect/connect.csproj @@ -0,0 +1,13 @@ + + + + Exe + net5.0 + enable + + + + + + + diff --git a/docs/examples/csharp/cloud-example/stmt/Program.cs b/docs/examples/csharp/cloud-example/stmt/Program.cs new file mode 100644 index 0000000000000000000000000000000000000000..a13f27b31a9192015843a5623de7e1a3c013788c --- /dev/null +++ b/docs/examples/csharp/cloud-example/stmt/Program.cs @@ -0,0 +1,83 @@ +using System; +using TDengineWS.Impl; +using TDengineDriver; +using System.Runtime.InteropServices; + +namespace Cloud.Examples +{ + public class STMTExample + { + static void Main(string[] args) + { + string dsn = Environment.GetEnvironmentVariable("TDENGINE_CLOUD_DSN"); + IntPtr conn = Connect(dsn); + // assume table has been created. + // CREATE STABLE if not exists test.meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS (location BINARY(64), groupId INT) + string insert = "insert into ? using test.meters tags(?,?) values(?,?,?,?)"; + + // Init STMT + IntPtr stmt = LibTaosWS.WSStmtInit(conn); + + if (stmt != IntPtr.Zero) + { + // Prepare SQL + int code = LibTaosWS.WSStmtPrepare(stmt, insert); + ValidSTMTStep(code, stmt, "WSInit()"); + + // Bind child table name and tags + TAOS_MULTI_BIND[] tags = new TAOS_MULTI_BIND[2] { WSMultiBind.WSBindBinary(new string[] { "California.LosAngeles" }), WSMultiBind.WSBindInt(new int?[] { 6 }) }; + code = LibTaosWS.WSStmtSetTbnameTags(stmt, "test.d1005",tags, 2); + ValidSTMTStep(code, stmt, "WSStmtSetTbnameTags()"); + + // bind column value + TAOS_MULTI_BIND[] data = new TAOS_MULTI_BIND[4]; + data[0] = WSMultiBind.WSBindTimestamp(new long[] { 1538551000000, 1538552000000, 1538553000000, 1538554000000, 1538555000000 }); + data[1] = WSMultiBind.WSBindFloat(new float?[] { 10.30000F, 10.30000F, 11.30000F, 10.30000F, 10.80000F }); + data[2] = WSMultiBind.WSBindInt(new int?[] { 218, 219, 221, 222, 223 }); + data[3] = WSMultiBind.WSBindFloat(new float?[] { 0.28000F, 0.29000F, 0.30000F, 0.31000F, 0.32000F }); + code = LibTaosWS.WSStmtBindParamBatch(stmt, data, 4); + ValidSTMTStep(code, stmt, "WSStmtBindParamBatch"); + + LibTaosWS.WSStmtAddBatch(stmt); + ValidSTMTStep(code, stmt, "WSStmtAddBatch"); + + IntPtr affectRowPtr = Marshal.AllocHGlobal(Marshal.SizeOf(typeof(Int32))); + LibTaosWS.WSStmtExecute(stmt, affectRowPtr); + ValidSTMTStep(code, stmt, "WSStmtExecute"); + Console.WriteLine("STMT affect rows:{0}", Marshal.ReadInt32(affectRowPtr)); + + LibTaosWS.WSStmtClose(stmt); + + // Free allocated memory + Marshal.FreeHGlobal(affectRowPtr); + WSMultiBind.WSFreeTaosBind(tags); + WSMultiBind.WSFreeTaosBind(data); + } + // close connect + LibTaosWS.WSClose(conn); + } + + public static IntPtr Connect(string dsn) + { + // get connect + IntPtr conn = LibTaosWS.WSConnectWithDSN(dsn); + if (conn == IntPtr.Zero) + { + throw new Exception($"get connection failed,reason:{LibTaosWS.WSErrorStr(conn)},code:{LibTaosWS.WSErrorNo(conn)}"); + } + return conn; + } + + public static void ValidSTMTStep(int code, IntPtr wsStmt, string method) + { + if (code != 0) + { + throw new Exception($"{method} failed,reason: {LibTaosWS.WSErrorStr(wsStmt)}, code: {code}"); + } + else + { + Console.WriteLine("{0} success", method); + } + } + } +} \ No newline at end of file diff --git a/docs/examples/csharp/cloud-example/stmt/stmt.csproj b/docs/examples/csharp/cloud-example/stmt/stmt.csproj new file mode 100644 index 0000000000000000000000000000000000000000..4a7c03f79c941769f9e4d7c4be46cb0769c084ff --- /dev/null +++ b/docs/examples/csharp/cloud-example/stmt/stmt.csproj @@ -0,0 +1,13 @@ + + + + Exe + net5 + enable + + + + + + + diff --git a/docs/examples/csharp/cloud-example/usage/Program.cs b/docs/examples/csharp/cloud-example/usage/Program.cs new file mode 100644 index 0000000000000000000000000000000000000000..18afb6578cbbf73613c3060f023f5c88c6fc7c92 --- /dev/null +++ b/docs/examples/csharp/cloud-example/usage/Program.cs @@ -0,0 +1,92 @@ +using System; +using TDengineDriver; +using TDengineWS.Impl; +using System.Collections.Generic; + +namespace Cloud.Examples +{ + public class UsageExample + { + static void Main(string[] args) + { + string dsn = Environment.GetEnvironmentVariable("TDENGINE_CLOUD_DSN"); + IntPtr conn = Connect(dsn); + InsertData(conn); + SelectData(conn); + // close connect + LibTaosWS.WSClose(conn); + } + + public static IntPtr Connect(string dsn) + { + // get connect + IntPtr conn = LibTaosWS.WSConnectWithDSN(dsn); + if (conn == IntPtr.Zero) + { + throw new Exception($"get connection failed,reason:{LibTaosWS.WSErrorStr(conn)},code:{LibTaosWS.WSErrorNo(conn)}"); + } + return conn; + } + + + public static void InsertData(IntPtr conn) + { + string createTable = "CREATE STABLE if not exists test.meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS (location BINARY(64), groupId INT)"; + string insertData = "INSERT INTO " + + "test.d1001 USING test.meters TAGS('California.SanFrancisco', 1) VALUES ('2018-10-03 14:38:05.000', 10.30000, 219, 0.31000)" + + "test.d1002 USING test.meters TAGS('California.SanFrancisco', 2) VALUES ('2018-10-03 14:38:16.650', 10.30000, 218, 0.25000)" + + "test.d1003 USING test.meters TAGS('California.LosAngeles', 3) VALUES ('2018-10-03 14:38:05.500', 11.80000, 221, 0.28000)" + + "test.d1004 USING test.meters TAGS('California.LosAngeles', 4) VALUES ('2018-10-03 14:38:05.000', 10.80000, 223, 0.29000) "; + + // create database under database named 'test' + IntPtr res = LibTaosWS.WSQuery(conn, createTable); + ValidQueryExecution(res); + // Free the query result every time when used up it. + LibTaosWS.WSFreeResult(res); + + // insert data into the table created in previous step. + res = LibTaosWS.WSQuery(conn, insertData); + ValidQueryExecution(res); + // Free the query result every time when used up it. + LibTaosWS.WSFreeResult(res); + } + public static void SelectData(IntPtr conn) + { + string selectTable = "select * from test.meters"; + IntPtr res = LibTaosWS.WSQueryTimeout(conn, selectTable,5000); + ValidQueryExecution(res); + + // print meta + List metas = LibTaosWS.WSGetFields(res); + foreach (var meta in metas) + { + Console.Write("{0} {1}({2})\t|", meta.name, meta.TypeName(), meta.size); + } + Console.WriteLine(""); + List dataSet = LibTaosWS.WSGetData(res); + 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(""); + } + Console.WriteLine(""); + + // Free the query result every time when used up it. + LibTaosWS.WSFreeResult(res); + } + + // Check if LibTaosWS.Query() execute correctly. + public static void ValidQueryExecution(IntPtr res) + { + int code = LibTaosWS.WSErrorNo(res); + if (code != 0) + { + throw new Exception($"execute SQL failed: reason: {LibTaosWS.WSErrorStr(res)}, code:{code}"); + } + } + } +} \ No newline at end of file diff --git a/docs/examples/csharp/cloud-example/usage/usage.csproj b/docs/examples/csharp/cloud-example/usage/usage.csproj new file mode 100644 index 0000000000000000000000000000000000000000..757d36dc10af7c36b9c87a5876151a5450ef7c84 --- /dev/null +++ b/docs/examples/csharp/cloud-example/usage/usage.csproj @@ -0,0 +1,13 @@ + + + + Exe + net5.0 + enable + + + + + + + diff --git a/docs/examples/csharp/AsyncQueryExample.cs b/docs/examples/csharp/native-example/AsyncQueryExample.cs similarity index 100% rename from docs/examples/csharp/AsyncQueryExample.cs rename to docs/examples/csharp/native-example/AsyncQueryExample.cs diff --git a/docs/examples/csharp/ConnectExample.cs b/docs/examples/csharp/native-example/ConnectExample.cs similarity index 100% rename from docs/examples/csharp/ConnectExample.cs rename to docs/examples/csharp/native-example/ConnectExample.cs diff --git a/docs/examples/csharp/InfluxDBLineExample.cs b/docs/examples/csharp/native-example/InfluxDBLineExample.cs similarity index 100% rename from docs/examples/csharp/InfluxDBLineExample.cs rename to docs/examples/csharp/native-example/InfluxDBLineExample.cs diff --git a/docs/examples/csharp/OptsJsonExample.cs b/docs/examples/csharp/native-example/OptsJsonExample.cs similarity index 100% rename from docs/examples/csharp/OptsJsonExample.cs rename to docs/examples/csharp/native-example/OptsJsonExample.cs diff --git a/docs/examples/csharp/OptsTelnetExample.cs b/docs/examples/csharp/native-example/OptsTelnetExample.cs similarity index 100% rename from docs/examples/csharp/OptsTelnetExample.cs rename to docs/examples/csharp/native-example/OptsTelnetExample.cs diff --git a/docs/examples/csharp/QueryExample.cs b/docs/examples/csharp/native-example/QueryExample.cs similarity index 100% rename from docs/examples/csharp/QueryExample.cs rename to docs/examples/csharp/native-example/QueryExample.cs diff --git a/docs/examples/csharp/SQLInsertExample.cs b/docs/examples/csharp/native-example/SQLInsertExample.cs similarity index 100% rename from docs/examples/csharp/SQLInsertExample.cs rename to docs/examples/csharp/native-example/SQLInsertExample.cs diff --git a/docs/examples/csharp/StmtInsertExample.cs b/docs/examples/csharp/native-example/StmtInsertExample.cs similarity index 100% rename from docs/examples/csharp/StmtInsertExample.cs rename to docs/examples/csharp/native-example/StmtInsertExample.cs diff --git a/docs/examples/csharp/SubscribeDemo.cs b/docs/examples/csharp/native-example/SubscribeDemo.cs similarity index 100% rename from docs/examples/csharp/SubscribeDemo.cs rename to docs/examples/csharp/native-example/SubscribeDemo.cs diff --git a/docs/examples/csharp/asyncquery.csproj b/docs/examples/csharp/native-example/asyncquery.csproj similarity index 100% rename from docs/examples/csharp/asyncquery.csproj rename to docs/examples/csharp/native-example/asyncquery.csproj diff --git a/docs/examples/csharp/connect.csproj b/docs/examples/csharp/native-example/connect.csproj similarity index 100% rename from docs/examples/csharp/connect.csproj rename to docs/examples/csharp/native-example/connect.csproj diff --git a/docs/examples/csharp/influxdbline.csproj b/docs/examples/csharp/native-example/influxdbline.csproj similarity index 100% rename from docs/examples/csharp/influxdbline.csproj rename to docs/examples/csharp/native-example/influxdbline.csproj diff --git a/docs/examples/csharp/optsjson.csproj b/docs/examples/csharp/native-example/optsjson.csproj similarity index 100% rename from docs/examples/csharp/optsjson.csproj rename to docs/examples/csharp/native-example/optsjson.csproj diff --git a/docs/examples/csharp/optstelnet.csproj b/docs/examples/csharp/native-example/optstelnet.csproj similarity index 100% rename from docs/examples/csharp/optstelnet.csproj rename to docs/examples/csharp/native-example/optstelnet.csproj diff --git a/docs/examples/csharp/query.csproj b/docs/examples/csharp/native-example/query.csproj similarity index 100% rename from docs/examples/csharp/query.csproj rename to docs/examples/csharp/native-example/query.csproj diff --git a/docs/examples/csharp/sqlinsert.csproj b/docs/examples/csharp/native-example/sqlinsert.csproj similarity index 100% rename from docs/examples/csharp/sqlinsert.csproj rename to docs/examples/csharp/native-example/sqlinsert.csproj diff --git a/docs/examples/csharp/stmtinsert.csproj b/docs/examples/csharp/native-example/stmtinsert.csproj similarity index 100% rename from docs/examples/csharp/stmtinsert.csproj rename to docs/examples/csharp/native-example/stmtinsert.csproj diff --git a/docs/examples/csharp/subscribe.csproj b/docs/examples/csharp/native-example/subscribe.csproj similarity index 100% rename from docs/examples/csharp/subscribe.csproj rename to docs/examples/csharp/native-example/subscribe.csproj