C# Connector

C# Connector

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.

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.

Note: TDengine Connector 3.x is not compatible with TDengine 2.x. In an environment with TDengine 2.x, you must use TDengine.Connector 1.x for the C# connector.

The source code of TDengine.Connector is hosted on GitHub.

Supported platforms

The supported platforms are the same as those supported by the TDengine client driver.

Version support

Please refer to version support list

Supported features

Native Connection
WebSocket Connection
Connection Management
General Query
Continuous Query
Parameter Binding
Subscription
Schemaless
Connection Management
General Query
Continuous Query
Parameter Binding

Installation Steps

Pre-installation preparation

Install the .NET SDK
Nuget Client (optional installation)
Install TDengine client driver, please refer to Install client driver for details

Install via dotnet CLI

Get C# driver using dotnet CLI
Use source code to get C# driver

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.

1. dotnet add package TDengine.Connector

You can download the source code and directly reference the latest version of the TDengine.Connector library.

1. git clone -b 3.0 https://github.com/taosdata/taos-connector-dotnet.git
2. cd taos-connector-dotnet
3. cp -r src/ myProject

5. cd myProject
6. dotnet add exmaple.csproj reference src/TDengine.csproj

Establish a Connection

Native Connection
WebSocket Connection

1. using TDengineDriver;

3. namespace TDengineExample
4. {

6. internal class EstablishConnection
7. {
8. static void Main(String[] args)
9. {
10. string host = "localhost";
11. short port = 6030;
12. string username = "root";
13. string password = "taosdata";
14. string dbname = "";

16. var conn = TDengine.Connect(host, username, password, dbname, port);
17. if (conn == IntPtr.Zero)
18. {
19. Console.WriteLine("Connect to TDengine failed");
20. }
21. else
22. {
23. Console.WriteLine("Connect to TDengine success");
24. }
25. TDengine.Close(conn);
26. TDengine.Cleanup();
27. }
28. }
29. }

The structure of the DSN description string is as follows:

1. [<protocol>]://[[<username>:<password>@]<host>:<port>][/<database>][?<p1>=<v1>[&<p2>=<v2>]]
2. |------------|---|-----------|-----------|------|------|------------|-----------------------|
3. |   protocol |   | username  | password  | host | port |  database  |  params               |

The parameters are described as follows:

protocol: Specify which connection method to use (support http/ws). For example, ws://localhost:6041 uses Websocket to establish connections.
username/password: Username and password used to create connections.
host/port: Specifies the server and port to establish a connection. Websocket connections default to localhost:6041.
database: Specify the default database to connect to. It’s optional.
params：Optional parameters.

A sample DSN description string is as follows:

1. ws://localhost:6041/test

1. using System;
2. using TDengineWS.Impl;

4. namespace Examples
5. {
6. public class WSConnExample
7. {
8. static int Main(string[] args)
9. {
10. string DSN = "ws://root:taosdata@127.0.0.1:6041/test";
11. IntPtr wsConn = LibTaosWS.WSConnectWithDSN(DSN);

13. if (wsConn == IntPtr.Zero)
14. {
15. Console.WriteLine("get WS connection failed");
16. return -1;
17. }
18. else
19. {
20. Console.WriteLine("Establish connect success.");
21. // close connection.
22. LibTaosWS.WSClose(wsConn);
23. }

25. return 0;
26. }
27. }
28. }

view source code

Usage examples

Write data

SQL Write

Native Connection
WebSocket Connection

1. using TDengineDriver;

4. namespace TDengineExample
5. {
6. internal class SQLInsertExample
7. {

9. static void Main()
10. {
11. IntPtr conn = GetConnection();
12. try
13. {
14. IntPtr res = TDengine.Query(conn, "CREATE DATABASE power");
15. CheckRes(conn, res, "failed to create database");
16. res = TDengine.Query(conn, "USE power");
17. CheckRes(conn, res, "failed to change database");
18. res = TDengine.Query(conn, "CREATE STABLE power.meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS (location BINARY(64), groupId INT)");
19. CheckRes(conn, res, "failed to create stable");
20. var sql = "INSERT INTO d1001 USING 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) " +
21. "d1002 USING power.meters TAGS('California.SanFrancisco', 3) VALUES('2018-10-03 14:38:16.650', 10.30000, 218, 0.25000) " +
22. "d1003 USING power.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) " +
23. "d1004 USING power.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)";
24. res = TDengine.Query(conn, sql);
25. CheckRes(conn, res, "failed to insert data");
26. int affectedRows = TDengine.AffectRows(res);
27. Console.WriteLine("affectedRows " + affectedRows);
28. TDengine.FreeResult(res);
29. }
30. finally
31. {
32. TDengine.Close(conn);
33. }

35. }

37. static IntPtr GetConnection()
38. {
39. string host = "localhost";
40. short port = 6030;
41. string username = "root";
42. string password = "taosdata";
43. string dbname = "";
44. var conn = TDengine.Connect(host, username, password, dbname, port);
45. if (conn == IntPtr.Zero)
46. {
47. throw new Exception("Connect to TDengine failed");
48. }
49. else
50. {
51. Console.WriteLine("Connect to TDengine success");
52. }
53. return conn;
54. }

56. static void CheckRes(IntPtr conn, IntPtr res, String errorMsg)
57. {
58. if (TDengine.ErrorNo(res) != 0)
59. {
60. throw new Exception($"{errorMsg} since: {TDengine.Error(res)}");
61. }
62. }

64. }
65. }

67. // output:
68. // Connect to TDengine success
69. // affectedRows 8

view source code

1. using System;
2. using TDengineWS.Impl;

4. namespace Examples
5. {
6. public class WSInsertExample
7. {
8. static int Main(string[] args)
9. {
10. string DSN = "ws://root:taosdata@127.0.0.1:6041/test";
11. IntPtr wsConn = LibTaosWS.WSConnectWithDSN(DSN);

13. // Assert if connection is validate
14. if (wsConn == IntPtr.Zero)
15. {
16. Console.WriteLine("get WS connection failed");
17. return -1;
18. }
19. else
20. {
21. Console.WriteLine("Establish connect success.");
22. }

24. string createTable = "CREATE STABLE test.meters (ts timestamp, current float, voltage int, phase float) TAGS (location binary(64), groupId int);";
25. 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)" +
26. "test.d1002 USING test.meters TAGS('California.SanFrancisco', 3) VALUES('2018-10-03 14:38:16.650', 10.30000, 218, 0.25000)" +
27. "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) " +
28. "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)";

30. IntPtr wsRes = LibTaosWS.WSQuery(wsConn, createTable);
31. ValidInsert("create table", wsRes);
32. LibTaosWS.WSFreeResult(wsRes);

34. wsRes = LibTaosWS.WSQuery(wsConn, insert);
35. ValidInsert("insert data", wsRes);
36. LibTaosWS.WSFreeResult(wsRes);

38. // close connection.
39. LibTaosWS.WSClose(wsConn);

41. return 0;
42. }

44. static void ValidInsert(string desc, IntPtr wsRes)
45. {
46. int code = LibTaosWS.WSErrorNo(wsRes);
47. if (code != 0)
48. {
49. Console.WriteLine($"execute SQL failed: reason: {LibTaosWS.WSErrorStr(wsRes)}, code:{code}");
50. }
51. else
52. {
53. Console.WriteLine("{0} success affect {2} rows, cost {1} nanoseconds", desc, LibTaosWS.WSTakeTiming(wsRes), LibTaosWS.WSAffectRows(wsRes));
54. }
55. }
56. }

58. }
59. // Establish connect success.
60. // create table success affect 0 rows, cost 3717542 nanoseconds
61. // insert data success affect 8 rows, cost 2613637 nanoseconds

view source code

InfluxDB line protocol write

1. using TDengineDriver;

3. namespace TDengineExample
4. {
5. internal class InfluxDBLineExample
6. {
7. static void Main()
8. {
9. IntPtr conn = GetConnection();
10. PrepareDatabase(conn);
11. string[] lines = {
12. "meters,location=California.LosAngeles,groupid=2 current=11.8,voltage=221,phase=0.28 1648432611249",
13. "meters,location=California.LosAngeles,groupid=2 current=13.4,voltage=223,phase=0.29 1648432611250",
14. "meters,location=California.LosAngeles,groupid=3 current=10.8,voltage=223,phase=0.29 1648432611249",
15. "meters,location=California.LosAngeles,groupid=3 current=11.3,voltage=221,phase=0.35 1648432611250"
16. };
17. IntPtr res = TDengine.SchemalessInsert(conn, lines, lines.Length, (int)TDengineSchemalessProtocol.TSDB_SML_LINE_PROTOCOL, (int)TDengineSchemalessPrecision.TSDB_SML_TIMESTAMP_MILLI_SECONDS);
18. if (TDengine.ErrorNo(res) != 0)
19. {
20. throw new Exception("SchemalessInsert failed since " + TDengine.Error(res));
21. }
22. else
23. {
24. int affectedRows = TDengine.AffectRows(res);
25. Console.WriteLine($"SchemalessInsert success, affected {affectedRows} rows");
26. }
27. TDengine.FreeResult(res);

29. }
30. static IntPtr GetConnection()
31. {
32. string host = "localhost";
33. short port = 6030;
34. string username = "root";
35. string password = "taosdata";
36. string dbname = "";
37. var conn = TDengine.Connect(host, username, password, dbname, port);
38. if (conn == IntPtr.Zero)
39. {
40. throw new Exception("Connect to TDengine failed");
41. }
42. else
43. {
44. Console.WriteLine("Connect to TDengine success");
45. }
46. return conn;
47. }

49. static void PrepareDatabase(IntPtr conn)
50. {
51. IntPtr res = TDengine.Query(conn, "CREATE DATABASE test");
52. if (TDengine.ErrorNo(res) != 0)
53. {
54. throw new Exception("failed to create database, reason: " + TDengine.Error(res));
55. }
56. res = TDengine.Query(conn, "USE test");
57. if (TDengine.ErrorNo(res) != 0)
58. {
59. throw new Exception("failed to change database, reason: " + TDengine.Error(res));
60. }
61. }

63. }

65. }

view source code

OpenTSDB Telnet line protocol write

1. using TDengineDriver;

3. namespace TDengineExample
4. {
5. internal class OptsTelnetExample
6. {
7. static void Main()
8. {
9. IntPtr conn = GetConnection();
10. try
11. {
12. PrepareDatabase(conn);
13. string[] lines = {
14. "meters.current 1648432611249 10.3 location=California.SanFrancisco groupid=2",
15. "meters.current 1648432611250 12.6 location=California.SanFrancisco groupid=2",
16. "meters.current 1648432611249 10.8 location=California.LosAngeles groupid=3",
17. "meters.current 1648432611250 11.3 location=California.LosAngeles groupid=3",
18. "meters.voltage 1648432611249 219 location=California.SanFrancisco groupid=2",
19. "meters.voltage 1648432611250 218 location=California.SanFrancisco groupid=2",
20. "meters.voltage 1648432611249 221 location=California.LosAngeles groupid=3",
21. "meters.voltage 1648432611250 217 location=California.LosAngeles groupid=3",
22. };
23. IntPtr res = TDengine.SchemalessInsert(conn, lines, lines.Length, (int)TDengineSchemalessProtocol.TSDB_SML_TELNET_PROTOCOL, (int)TDengineSchemalessPrecision.TSDB_SML_TIMESTAMP_NOT_CONFIGURED);
24. if (TDengine.ErrorNo(res) != 0)
25. {
26. throw new Exception("SchemalessInsert failed since " + TDengine.Error(res));
27. }
28. else
29. {
30. int affectedRows = TDengine.AffectRows(res);
31. Console.WriteLine($"SchemalessInsert success, affected {affectedRows} rows");
32. }
33. TDengine.FreeResult(res);
34. }
35. catch
36. {
37. TDengine.Close(conn);
38. }
39. }
40. static IntPtr GetConnection()
41. {
42. string host = "localhost";
43. short port = 6030;
44. string username = "root";
45. string password = "taosdata";
46. string dbname = "";
47. var conn = TDengine.Connect(host, username, password, dbname, port);
48. if (conn == IntPtr.Zero)
49. {
50. throw new Exception("Connect to TDengine failed");
51. }
52. else
53. {
54. Console.WriteLine("Connect to TDengine success");
55. }
56. return conn;
57. }

59. static void PrepareDatabase(IntPtr conn)
60. {
61. IntPtr res = TDengine.Query(conn, "CREATE DATABASE test");
62. if (TDengine.ErrorNo(res) != 0)
63. {
64. throw new Exception("failed to create database, reason: " + TDengine.Error(res));
65. }
66. res = TDengine.Query(conn, "USE test");
67. if (TDengine.ErrorNo(res) != 0)
68. {
69. throw new Exception("failed to change database, reason: " + TDengine.Error(res));
70. }
71. }
72. }
73. }

view source code

OpenTSDB JSON line protocol write

1. using TDengineDriver;

3. namespace TDengineExample
4. {
5. internal class OptsJsonExample
6. {
7. static void Main()
8. {
9. IntPtr conn = GetConnection();
10. try
11. {
12. PrepareDatabase(conn);
13. string[] lines = { "[{\"metric\": \"meters.current\", \"timestamp\": 1648432611249, \"value\": 10.3, \"tags\": {\"location\": \"California.SanFrancisco\", \"groupid\": 2}}," +
14. " {\"metric\": \"meters.voltage\", \"timestamp\": 1648432611249, \"value\": 219, \"tags\": {\"location\": \"California.LosAngeles\", \"groupid\": 1}}, " +
15. "{\"metric\": \"meters.current\", \"timestamp\": 1648432611250, \"value\": 12.6, \"tags\": {\"location\": \"California.SanFrancisco\", \"groupid\": 2}}," +
16. " {\"metric\": \"meters.voltage\", \"timestamp\": 1648432611250, \"value\": 221, \"tags\": {\"location\": \"California.LosAngeles\", \"groupid\": 1}}]"
17. };

19. IntPtr res = TDengine.SchemalessInsert(conn, lines, 1, (int)TDengineSchemalessProtocol.TSDB_SML_JSON_PROTOCOL, (int)TDengineSchemalessPrecision.TSDB_SML_TIMESTAMP_NOT_CONFIGURED);
20. if (TDengine.ErrorNo(res) != 0)
21. {
22. throw new Exception("SchemalessInsert failed since " + TDengine.Error(res));
23. }
24. else
25. {
26. int affectedRows = TDengine.AffectRows(res);
27. Console.WriteLine($"SchemalessInsert success, affected {affectedRows} rows");
28. }
29. TDengine.FreeResult(res);
30. }
31. finally
32. {
33. TDengine.Close(conn);
34. }
35. }
36. static IntPtr GetConnection()
37. {
38. string host = "localhost";
39. short port = 6030;
40. string username = "root";
41. string password = "taosdata";
42. string dbname = "";
43. var conn = TDengine.Connect(host, username, password, dbname, port);
44. if (conn == IntPtr.Zero)
45. {
46. throw new Exception("Connect to TDengine failed");
47. }
48. else
49. {
50. Console.WriteLine("Connect to TDengine success");
51. }
52. return conn;
53. }

55. static void PrepareDatabase(IntPtr conn)
56. {
57. IntPtr res = TDengine.Query(conn, "CREATE DATABASE test");
58. if (TDengine.ErrorNo(res) != 0)
59. {
60. throw new Exception("failed to create database, reason: " + TDengine.Error(res));
61. }
62. res = TDengine.Query(conn, "USE test");
63. if (TDengine.ErrorNo(res) != 0)
64. {
65. throw new Exception("failed to change database, reason: " + TDengine.Error(res));
66. }
67. }
68. }
69. }

view source code

Parameter Binding

Native Connection
WebSocket Connection

1. using TDengineDriver;

3. namespace TDengineExample
4. {
5. internal class StmtInsertExample
6. {
7. private static IntPtr conn;
8. private static IntPtr stmt;
9. static void Main()
10. {
11. conn = GetConnection();
12. try
13. {
14. PrepareSTable();
15. // 1. init and prepare
16. stmt = TDengine.StmtInit(conn);
17. if (stmt == IntPtr.Zero)
18. {
19. throw new Exception("failed to init stmt.");
20. }
21. int res = TDengine.StmtPrepare(stmt, "INSERT INTO ? USING meters TAGS(?, ?) VALUES(?, ?, ?, ?)");
22. CheckStmtRes(res, "failed to prepare stmt");

24. // 2. bind table name and tags
25. TAOS_MULTI_BIND[] tags = new TAOS_MULTI_BIND[2] { TaosMultiBind.MultiBindBinary(new string[] { "California.SanFrancisco" }), TaosMultiBind.MultiBindInt(new int?[] { 2 }) };
26. res = TDengine.StmtSetTbnameTags(stmt, "d1001", tags);
27. CheckStmtRes(res, "failed to bind table name and tags");

29. // 3. bind values
30. TAOS_MULTI_BIND[] values = new TAOS_MULTI_BIND[4] {
31. TaosMultiBind.MultiBindTimestamp(new long[2] { 1648432611249, 1648432611749}),
32. TaosMultiBind.MultiBindFloat(new float?[2] { 10.3f, 12.6f}),
33. TaosMultiBind.MultiBindInt(new int?[2] { 219, 218}),
34. TaosMultiBind.MultiBindFloat(new float?[2]{ 0.31f, 0.33f})
35. };
36. res = TDengine.StmtBindParamBatch(stmt, values);
37. CheckStmtRes(res, "failed to bind params");

39. // 4. add batch
40. res = TDengine.StmtAddBatch(stmt);
41. CheckStmtRes(res, "failed to add batch");

43. // 5. execute
44. res = TDengine.StmtExecute(stmt);
45. CheckStmtRes(res, "faild to execute");

47. // 6. free
48. TaosMultiBind.FreeTaosBind(tags);
49. TaosMultiBind.FreeTaosBind(values);
50. }
51. finally
52. {
53. TDengine.Close(conn);
54. }

56. }

58. static IntPtr GetConnection()
59. {
60. string host = "localhost";
61. short port = 6030;
62. string username = "root";
63. string password = "taosdata";
64. string dbname = "";
65. var conn = TDengine.Connect(host, username, password, dbname, port);
66. if (conn == IntPtr.Zero)
67. {
68. throw new Exception("Connect to TDengine failed");
69. }
70. else
71. {
72. Console.WriteLine("Connect to TDengine success");
73. }
74. return conn;
75. }

77. static void PrepareSTable()
78. {
79. IntPtr res = TDengine.Query(conn, "CREATE DATABASE power");
80. CheckResPtr(res, "failed to create database");
81. res = TDengine.Query(conn, "USE power");
82. CheckResPtr(res, "failed to change database");
83. res = TDengine.Query(conn, "CREATE STABLE power.meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS (location BINARY(64), groupId INT)");
84. CheckResPtr(res, "failed to create stable");
85. }

87. static void CheckStmtRes(int res, string errorMsg)
88. {
89. if (res != 0)
90. {
91. Console.WriteLine(errorMsg + ", " + TDengine.StmtErrorStr(stmt));
92. int code = TDengine.StmtClose(stmt);
93. if (code != 0)
94. {
95. throw new Exception($"falied to close stmt, {code} reason: {TDengine.StmtErrorStr(stmt)} ");
96. }
97. }
98. }

100. static void CheckResPtr(IntPtr res, string errorMsg)
101. {
102. if (TDengine.ErrorNo(res) != 0)
103. {
104. throw new Exception(errorMsg + " since:" + TDengine.Error(res));
105. }
106. }

108. }
109. }

view source code

1. using System;
2. using TDengineWS.Impl;
3. using TDengineDriver;
4. using System.Runtime.InteropServices;

6. namespace Examples
7. {
8. public class WSStmtExample
9. {
10. static int Main(string[] args)
11. {
12. const string DSN = "ws://root:taosdata@127.0.0.1:6041/test";
13. const string table = "meters";
14. const string database = "test";
15. const string childTable = "d1005";
16. string insert = $"insert into ? using {database}.{table} tags(?,?) values(?,?,?,?)";
17. const int numOfTags = 2;
18. const int numOfColumns = 4;

20. // Establish connection
21. IntPtr wsConn = LibTaosWS.WSConnectWithDSN(DSN);
22. if (wsConn == IntPtr.Zero)
23. {
24. Console.WriteLine($"get WS connection failed");
25. return -1;
26. }
27. else
28. {
29. Console.WriteLine("Establish connect success...");
30. }

32. // init stmt
33. IntPtr wsStmt = LibTaosWS.WSStmtInit(wsConn);
34. if (wsStmt != IntPtr.Zero)
35. {
36. int code = LibTaosWS.WSStmtPrepare(wsStmt, insert);
37. ValidStmtStep(code, wsStmt, "WSStmtPrepare");

39. TAOS_MULTI_BIND[] wsTags = new TAOS_MULTI_BIND[] { WSMultiBind.WSBindNchar(new string[] { "California.SanDiego" }), WSMultiBind.WSBindInt(new int?[] { 4 }) };
40. code = LibTaosWS.WSStmtSetTbnameTags(wsStmt, $"{database}.{childTable}", wsTags, numOfTags);
41. ValidStmtStep(code, wsStmt, "WSStmtSetTbnameTags");

43. TAOS_MULTI_BIND[] data = new TAOS_MULTI_BIND[4];
44. data[0] = WSMultiBind.WSBindTimestamp(new long[] { 1538548687000, 1538548688000, 1538548689000, 1538548690000, 1538548691000 });
45. data[1] = WSMultiBind.WSBindFloat(new float?[] { 10.30F, 10.40F, 10.50F, 10.60F, 10.70F });
46. data[2] = WSMultiBind.WSBindInt(new int?[] { 223, 221, 222, 220, 219 });
47. data[3] = WSMultiBind.WSBindFloat(new float?[] { 0.31F, 0.32F, 0.33F, 0.35F, 0.28F });
48. code = LibTaosWS.WSStmtBindParamBatch(wsStmt, data, numOfColumns);
49. ValidStmtStep(code, wsStmt, "WSStmtBindParamBatch");

51. code = LibTaosWS.WSStmtAddBatch(wsStmt);
52. ValidStmtStep(code, wsStmt, "WSStmtAddBatch");

54. IntPtr stmtAffectRowPtr = Marshal.AllocHGlobal(Marshal.SizeOf(typeof(Int32)));
55. code = LibTaosWS.WSStmtExecute(wsStmt, stmtAffectRowPtr);
56. ValidStmtStep(code, wsStmt, "WSStmtExecute");
57. Console.WriteLine("WS STMT insert {0} rows...", Marshal.ReadInt32(stmtAffectRowPtr));
58. Marshal.FreeHGlobal(stmtAffectRowPtr);

60. LibTaosWS.WSStmtClose(wsStmt);

62. // Free unmanaged memory
63. WSMultiBind.WSFreeTaosBind(wsTags);
64. WSMultiBind.WSFreeTaosBind(data);

66. //check result with SQL "SELECT * FROM test.d1005;"
67. }
68. else
69. {
70. Console.WriteLine("Init STMT failed...");
71. }

73. // close connection.
74. LibTaosWS.WSClose(wsConn);

76. return 0;
77. }

79. static void ValidStmtStep(int code, IntPtr wsStmt, string desc)
80. {
81. if (code != 0)
82. {
83. Console.WriteLine($"{desc} failed,reason: {LibTaosWS.WSErrorStr(wsStmt)}, code: {code}");
84. }
85. else
86. {
87. Console.WriteLine("{0} success...", desc);
88. }
89. }
90. }
91. }

93. // WSStmtPrepare success...
94. // WSStmtSetTbnameTags success...
95. // WSStmtBindParamBatch success...
96. // WSStmtAddBatch success...
97. // WSStmtExecute success...
98. // WS STMT insert 5 rows...

view source code

Query data

Synchronous Query

Native Connection
WebSocket Connection

1. using TDengineDriver;
2. using TDengineDriver.Impl;
3. using System.Runtime.InteropServices;

5. namespace TDengineExample
6. {
7. internal class QueryExample
8. {
9. static void Main()
10. {
11. IntPtr conn = GetConnection();
12. try
13. {
14. // run query
15. IntPtr res = TDengine.Query(conn, "SELECT * FROM meters LIMIT 2");
16. if (TDengine.ErrorNo(res) != 0)
17. {
18. throw new Exception("Failed to query since: " + TDengine.Error(res));
19. }

21. // get filed count
22. int fieldCount = TDengine.FieldCount(res);
23. Console.WriteLine("fieldCount=" + fieldCount);

25. // print column names
26. List<TDengineMeta> metas = LibTaos.GetMeta(res);
27. for (int i = 0; i < metas.Count; i++)
28. {
29. Console.Write(metas[i].name + "\t");
30. }
31. Console.WriteLine();

33. // print values
34. List<Object> resData = LibTaos.GetData(res);
35. for (int i = 0; i < resData.Count; i++)
36. {
37. Console.Write($"|{resData[i].ToString()} \t");
38. if (((i + 1) % metas.Count == 0))
39. {
40. Console.WriteLine("");
41. }
42. }
43. Console.WriteLine();

45. // Free result after use
46. TDengine.FreeResult(res);
47. }
48. finally
49. {
50. TDengine.Close(conn);
51. }

53. }
54. static IntPtr GetConnection()
55. {
56. string host = "localhost";
57. short port = 6030;
58. string username = "root";
59. string password = "taosdata";
60. string dbname = "power";
61. var conn = TDengine.Connect(host, username, password, dbname, port);
62. if (conn == IntPtr.Zero)
63. {
64. throw new Exception("Connect to TDengine failed");
65. }
66. else
67. {
68. Console.WriteLine("Connect to TDengine success");
69. }
70. return conn;
71. }
72. }
73. }

75. // output:
76. // Connect to TDengine success
77. // fieldCount=6
78. // ts      current voltage phase   location        groupid
79. // 1648432611249   10.3    219     0.31    California.SanFrancisco        2
80. // 1648432611749   12.6    218     0.33    California.SanFrancisco        2

view source code

1. using System;
2. using TDengineWS.Impl;
3. using System.Collections.Generic;
4. using TDengineDriver;

6. namespace Examples
7. {
8. public class WSQueryExample
9. {
10. static int Main(string[] args)
11. {
12. string DSN = "ws://root:taosdata@127.0.0.1:6041/test";
13. IntPtr wsConn = LibTaosWS.WSConnectWithDSN(DSN);
14. if (wsConn == IntPtr.Zero)
15. {
16. Console.WriteLine("get WS connection failed");
17. return -1;
18. }
19. else
20. {
21. Console.WriteLine("Establish connect success.");
22. }

24. string select = "select * from test.meters";

26. // optional:wsRes = LibTaosWS.WSQuery(wsConn, select);
27. IntPtr wsRes = LibTaosWS.WSQueryTimeout(wsConn, select, 1);
28. // Assert if query execute success.
29. int code = LibTaosWS.WSErrorNo(wsRes);
30. if (code != 0)
31. {
32. Console.WriteLine($"execute SQL failed: reason: {LibTaosWS.WSErrorStr(wsRes)}, code:{code}");
33. LibTaosWS.WSFreeResult(wsRes);
34. return -1;
35. }

37. // get meta data
38. List<TDengineMeta> metas = LibTaosWS.WSGetFields(wsRes);
39. // get retrieved data
40. List<object> dataSet = LibTaosWS.WSGetData(wsRes);

42. // do something with result.
43. foreach (var meta in metas)
44. {
45. Console.Write("{0} {1}({2}) \t|\t", meta.name, meta.TypeName(), meta.size);
46. }
47. Console.WriteLine("");

49. for (int i = 0; i < dataSet.Count;)
50. {
51. for (int j = 0; j < metas.Count; j++)
52. {
53. Console.Write("{0}\t|\t", dataSet[i]);
54. i++;
55. }
56. Console.WriteLine("");
57. }

59. // Free result after use.
60. LibTaosWS.WSFreeResult(wsRes);

62. // close connection.
63. LibTaosWS.WSClose(wsConn);

65. return 0;
66. }
67. }
68. }

70. // Establish connect success.
71. // ts TIMESTAMP(8)         |       current FLOAT(4)        |       voltage INT(4)  |       phase FLOAT(4)  |       location BINARY(64)     |       groupid INT(4)  |
72. // 1538548685000   |       10.8    |       223     |       0.29    |       California.LosAngeles   |       3       |
73. // 1538548686500   |       11.5    |       221     |       0.35    |       California.LosAngeles   |       3       |
74. // 1538548685500   |       11.8    |       221     |       0.28    |       California.LosAngeles   |       2       |
75. // 1538548696600   |       13.4    |       223     |       0.29    |       California.LosAngeles   |       2       |
76. // 1538548685000   |       10.3    |       219     |       0.31    |       California.SanFrancisco |       2       |
77. // 1538548695000   |       12.6    |       218     |       0.33    |       California.SanFrancisco |       2       |
78. // 1538548696800   |       12.3    |       221     |       0.31    |       California.SanFrancisco |       2       |
79. // 1538548696650   |       10.3    |       218     |       0.25    |       California.SanFrancisco |       3       |

view source code

Asynchronous query

1. using System;
2. using System.Collections.Generic;
3. using TDengineDriver;
4. using TDengineDriver.Impl;
5. using System.Runtime.InteropServices;

7. namespace TDengineExample
8. {
9. public class AsyncQueryExample
10. {
11. static void Main()
12. {
13. IntPtr conn = GetConnection();
14. try
15. {
16. QueryAsyncCallback queryAsyncCallback = new QueryAsyncCallback(QueryCallback);
17. TDengine.QueryAsync(conn, "select * from meters", queryAsyncCallback, IntPtr.Zero);
18. Thread.Sleep(2000);
19. }
20. finally
21. {
22. TDengine.Close(conn);
23. }

25. }

27. static void QueryCallback(IntPtr param, IntPtr taosRes, int code)
28. {
29. if (code == 0 && taosRes != IntPtr.Zero)
30. {
31. FetchRawBlockAsyncCallback fetchRowAsyncCallback = new FetchRawBlockAsyncCallback(FetchRawBlockCallback);
32. TDengine.FetchRawBlockAsync(taosRes, fetchRowAsyncCallback, param);
33. }
34. else
35. {
36. throw new Exception($"async query data failed,code:{code},reason:{TDengine.Error(taosRes)}");
37. }
38. }

40. // Iteratively call this interface until "numOfRows" is no greater than 0.
41. static void FetchRawBlockCallback(IntPtr param, IntPtr taosRes, int numOfRows)
42. {
43. if (numOfRows > 0)
44. {
45. Console.WriteLine($"{numOfRows} rows async retrieved");
46. IntPtr pdata = TDengine.GetRawBlock(taosRes);
47. List<TDengineMeta> metaList = TDengine.FetchFields(taosRes);
48. List<object> dataList = LibTaos.ReadRawBlock(pdata, metaList, numOfRows);

50. for (int i = 0; i < dataList.Count; i++)
51. {
52. if (i != 0 && (i + 1) % metaList.Count == 0)
53. {
54. Console.WriteLine("{0}\t|", dataList[i]);
55. }
56. else
57. {
58. Console.Write("{0}\t|", dataList[i]);
59. }
60. }
61. Console.WriteLine("");
62. TDengine.FetchRawBlockAsync(taosRes, FetchRawBlockCallback, param);
63. }
64. else
65. {
66. if (numOfRows == 0)
67. {
68. Console.WriteLine("async retrieve complete.");
69. }
70. else
71. {
72. throw new Exception($"FetchRawBlockCallback callback error, error code {numOfRows}");
73. }
74. TDengine.FreeResult(taosRes);
75. }
76. }

78. static IntPtr GetConnection()
79. {
80. string host = "localhost";
81. short port = 6030;
82. string username = "root";
83. string password = "taosdata";
84. string dbname = "power";
85. var conn = TDengine.Connect(host, username, password, dbname, port);
86. if (conn == IntPtr.Zero)
87. {
88. throw new Exception("Connect to TDengine failed");
89. }
90. else
91. {
92. Console.WriteLine("Connect to TDengine success");
93. }
94. return conn;
95. }
96. }
97. }

99. // //output:
100. // // Connect to TDengine success
101. // // 8 rows async retrieved

103. // // 1538548685500   |       11.8    |       221     |       0.28    |       california.losangeles   |       2       |
104. // // 1538548696600   |       13.4    |       223     |       0.29    |       california.losangeles   |       2       |
105. // // 1538548685000   |       10.8    |       223     |       0.29    |       california.losangeles   |       3       |
106. // // 1538548686500   |       11.5    |       221     |       0.35    |       california.losangeles   |       3       |
107. // // 1538548685000   |       10.3    |       219     |       0.31    |       california.sanfrancisco         |       2       |
108. // // 1538548695000   |       12.6    |       218     |       0.33    |       california.sanfrancisco         |       2       |
109. // // 1538548696800   |       12.3    |       221     |       0.31    |       california.sanfrancisco         |       2       |
110. // // 1538548696650   |       10.3    |       218     |       0.25    |       california.sanfrancisco         |       3       |
111. // // async retrieve complete.

view source code

More sample programs

Sample program	Sample program description
CURD	Table creation, data insertion, and query examples with TDengine.Connector
JSON Tag	Writing and querying JSON tag data with TDengine Connector
stmt	Parameter binding with TDengine Connector
schemaless	Schemaless writes with TDengine Connector
async query	Asynchronous queries with TDengine Connector
Subscription	Subscription example with TDengine Connector
Basic WebSocket Usage	WebSocket basic data in and out with TDengine connector
WebSocket Parameter Binding	WebSocket parameter binding example

Important update records

TDengine.Connector	Description
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.
1.0.6	Fix schemaless bug in 1.0.4 and 1.0.5.
1.0.5	Fix Windows sync query Chinese error bug.
1.0.4	Add asynchronous query, subscription, and other functions. Fix the binding parameter bug.
1.0.3	Add parameter binding, schemaless, JSON tag, etc.
1.0.2	Add connection management, synchronous query, error messages, etc.

Other descriptions

Third-party driver

Taos is an ADO.NET connector for TDengine, supporting Linux and Windows platforms. Community contributor Maikebing@@maikebing contributes the connector. Please refer to:

Interface download:<https://github.com/maikebing/Maikebing.EntityFrameworkCore.Taos>

Frequently Asked Questions

“Unable to establish connection”, “Unable to resolve FQDN”

Usually, it’s caused by an incorrect FQDN configuration. Please refer to this section in the FAQ to troubleshoot. 2. Unhandled exception. System.DllNotFoundException: Unable to load DLL ‘taos’ or one of its dependencies: The specified module cannot be found.

This is usually because the program did not find the dependent client driver. The solution is to copy C:\TDengine\driver\taos.dll to the C:\Windows\System32\ directory on Windows, and create the following soft link on Linux ln -s /usr/local/taos/driver/libtaos.so.x.x .x.x /usr/lib/libtaos.so will work.

C#

C# Connector

Supported platforms

Version support

Supported features

Installation Steps

Pre-installation preparation

Install via dotnet CLI

Establish a Connection

Usage examples

Write data

SQL Write

InfluxDB line protocol write

OpenTSDB Telnet line protocol write

OpenTSDB JSON line protocol write

Parameter Binding

Query data

Synchronous Query

Asynchronous query

More sample programs

Important update records

Other descriptions

Third-party driver

Frequently Asked Questions

API Reference