homework-jianmu/docs/en/14-reference/05-connector/40-csharp.md

809 lines
32 KiB
Markdown

---
toc_max_heading_level: 4
sidebar_label: C#
title: C# Client Library
slug: /tdengine-reference/client-libraries/csharp
---
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import RequestId from "../../assets/resources/_request_id.mdx";
`TDengine.Connector` is the C# language connector provided by TDengine. C# developers can use it to develop C# applications that access data in the TDengine cluster.
## .Net Version Compatibility
- Supports .NET Framework 4.6 and above.
- Supports .NET 5.0 and above.
## Supported Platforms
- Native connection supports the same platforms as the TDengine client driver.
- WebSocket connection supports all platforms that can run the .NET runtime.
## Version History
| Connector Version | Major Changes | TDengine Version |
|-------------------|------------------------------------------------------------|--------------------|
| 3.1.6 | Optimize WebSocket connection message handling. | - |
| 3.1.5 | Fix WebSocket encoding error for Chinese character length. | - |
| 3.1.4 | Improved WebSocket query and insert performance. | 3.3.2.0 and higher |
| 3.1.3 | Supported WebSocket auto-reconnect. | - |
| 3.1.2 | Fixed schemaless resource release. | - |
| 3.1.1 | Supported varbinary and geometry types. | - |
| 3.1.0 | WebSocket uses a native C# implementation. | 3.2.1.0 and higher |
## Exceptions and Error Codes
`TDengine.Connector` will throw exceptions, and applications need to handle these exceptions. The taosc exception type `TDengineError` includes an error code and error message, which applications can use to handle the error.
For error reporting in other TDengine modules, please refer to [Error Codes](../../error-codes/)
## Data Type Mapping
| TDengine DataType | C# Type |
|-------------------|----------|
| TIMESTAMP | DateTime |
| TINYINT | sbyte |
| SMALLINT | short |
| INT | int |
| BIGINT | long |
| TINYINT UNSIGNED | byte |
| SMALLINT UNSIGNED | ushort |
| INT UNSIGNED | uint |
| BIGINT UNSIGNED | ulong |
| FLOAT | float |
| DOUBLE | double |
| BOOL | bool |
| BINARY | byte[] |
| NCHAR | string |
| JSON | byte[] |
| VARBINARY | byte[] |
| GEOMETRY | byte[] |
**Note**: JSON type is only supported in tags.
The GEOMETRY type is binary data in little endian byte order, conforming to the WKB standard. For more details, please refer to [Data Types](../../sql-manual/data-types/)
For WKB standard, please refer to [Well-Known Binary (WKB)](https://libgeos.org/specifications/wkb/)
## Summary of Example Programs
For the source code of the example programs, please refer to: [Example Programs](https://github.com/taosdata/taos-connector-dotnet/tree/3.0/examples)
## API Reference
### ADO.NET Driver
The `TDengine.Data.Client` interface implements the ADO.NET driver, supporting connections to the TDengine database for data operations.
#### Parameter Specifications
ConnectionStringBuilder uses a key-value pair method to set connection parameters, where the key is the parameter name and the value is the parameter value, separated by semicolons `;`.
For example:
```csharp
"protocol=WebSocket;host=127.0.0.1;port=6041;useSSL=false"
```
##### Native Connection
For example: `"host=127.0.0.1;port=6030;username=root;password=taosdata;protocol=Native;db=test"`
Supported parameters include:
* `host`: Address of the TDengine instance.
* `port`: Port of the TDengine instance.
* `username`: Username for the connection.
* `password`: Password for the connection.
* `protocol`: Connection protocol, options are Native or WebSocket, default is Native.
* `db`: Database to connect to.
* `timezone`: Time zone, default is the local time zone.
##### WebSocket Connection
For example: `"protocol=WebSocket;host=127.0.0.1;port=6041;useSSL=false;enableCompression=true;autoReconnect=true;reconnectIntervalMs=10;reconnectRetryCount=5"`
Supported parameters include:
* `host`: Address of the TDengine instance.
* `port`: Port of the TDengine instance.
* `username`: Username for the connection.
* `password`: Password for the connection.
* `protocol`: Connection protocol, options are Native or WebSocket, default is Native.
* `db`: Database to connect to.
* `timezone`: Time zone, default is the local time zone.
* `connTimeout`: Connection timeout, default is 1 minute.
* `readTimeout`: Read timeout, default is 5 minutes.
* `writeTimeout`: Send timeout, default is 10 seconds.
* `token`: Token for connecting to TDengine cloud.
* `useSSL`: Whether to use SSL connection, default is false.
* `enableCompression`: Whether to enable WebSocket compression, default is false.
* `autoReconnect`: Whether to automatically reconnect, default is false.
* `reconnectRetryCount`: Number of retries for reconnection, default is 3.
* `reconnectIntervalMs`: Interval for reconnection in milliseconds, default is 2000.
#### Interface Description
The `ConnectionStringBuilder` class provides functionality for parsing connection configuration strings.
* `public ConnectionStringBuilder(string connectionString)`
* **Interface Description**: Constructor for ConnectionStringBuilder.
* **Parameter Description**:
* `connectionString`: Connection configuration string.
### Connection Features
The C# driver supports creating ADO.NET connections, returning objects that support the ADO.NET standard `DbConnection` interface, and also provides the `ITDengineClient` interface, which extends some schema-less write interfaces.
#### Standard Interfaces
The standard interfaces supported by ADO.NET connections are as follows:
* `public TDengineConnection(string connectionString)`
* **Interface Description**: Constructor for TDengineConnection.
* **Parameter Description**:
* `connectionString`: Connection configuration string.
* **Exception**: Throws `ArgumentException` if the format is incorrect.
* `public void ChangeDatabase(string databaseName)`
* **Interface Description**: Switch databases.
* **Parameter Description**:
* `databaseName`: Database name.
* **Exception**: Throws `TDengineError` exception if execution fails.
* `public void Close()`
* **Interface Description**: Close connection.
* `public void Open()`
* **Interface Description**: Open connection.
* **Exception**: Throws `TDengineError` exception if opening fails, be aware of potential network issues with WebSocket connections.
* `public string ServerVersion`
* **Interface Description**: Returns the server version.
* **Return Value**: Server version string.
* **Exception**: Throws `TDengineError` exception if execution fails.
* `public string DataSource`
* **Interface Description**: Returns the data source.
* **Return Value**: Configuration of the host used to create the connection.
* `public string Database`
* **Interface Description**: Returns the connected database.
* **Return Value**: Configuration of the database used to create the connection.
* `public TDengineCommand(TDengineConnection connection)`
* **Interface Description**: Constructor for TDengineCommand.
* **Parameter Description**:
* `connection`: TDengineConnection object.
* **Exception**: Throws `TDengineError` exception if execution fails.
* `public void Prepare()`
* **Interface Description**: Checks the connection and command text, and prepares for command execution.
* **Exception**: Throws `InvalidOperationException` if `open` has not been executed or `CommandText` is not set.
* `public string CommandText`
* **Interface Description**: Gets or sets the command text.
* **Return Value**: Command text.
* `public new virtual TDengineParameterCollection Parameters`
* **Interface Description**: Gets the parameter collection.
* **Return Value**: TDengineParameterCollection object.
#### Schemaless Writing
* `public static ITDengineClient Open(ConnectionStringBuilder builder)`
* **Interface Description**: Open connection.
* **Parameter Description**:
* `builder`: Connection configuration.
* **Return Value**: ITDengineClient interface.
* **Exception**: Throws `TDengineError` exception if opening fails, be aware of potential network issues with WebSocket connections.
* `void SchemalessInsert(string[] lines, TDengineSchemalessProtocol protocol,TDengineSchemalessPrecision precision, int ttl, long reqId)`
* **Interface Description**: Schemaless writing.
* **Parameter Description**:
* `lines`: Array of data lines.
* `protocol`: Data protocol, supported protocols: `TSDB_SML_LINE_PROTOCOL = 1` `TSDB_SML_TELNET_PROTOCOL = 2` `TSDB_SML_JSON_PROTOCOL = 3`.
* `precision`: Time precision, supported configurations: `TSDB_SML_TIMESTAMP_NOT_CONFIGURED = 0` `TSDB_SML_TIMESTAMP_HOURS = 1` `TSDB_SML_TIMESTAMP_MINUTES = 2` `TSDB_SML_TIMESTAMP_SECONDS = 3` `TSDB_SML_TIMESTAMP_MILLI_SECONDS = 4` `TSDB_SML_TIMESTAMP_MICRO_SECONDS = 5` `TSDB_SML_TIMESTAMP_NANO_SECONDS = 6`.
* `ttl`: Data expiration time, 0 means not configured.
* `reqId`: Request ID.
* **Exception**: Throws `TDengineError` exception if execution fails.
### Execute SQL
The C# driver provides a `DbCommand` interface that complies with the ADO.NET standard, supporting the following features:
1. **Execute SQL Statements**: Execute static SQL statements and return the resulting object.
2. **Query Execution**: Can execute queries that return a dataset (`SELECT` statements).
3. **Update Execution**: Can execute SQL statements that affect the number of rows, such as `INSERT`, `UPDATE`, `DELETE`, etc.
4. **Get Results**: Can obtain the result set (`ResultSet` object) returned after query execution and iterate through the returned data.
5. **Get Update Count**: For non-query SQL statements, can obtain the number of rows affected after execution.
6. **Close Resources**: Provides methods to close and release database resources.
Additionally, the C# driver also provides an extended interface for request link tracking.
#### Standard Interface
* `public int ExecuteNonQuery()`
* **Interface Description**: Executes an SQL statement and returns the number of rows affected.
* **Return Value**: Number of rows affected.
* **Exception**: Throws `TDengineError` exception on execution failure.
* `public object ExecuteScalar()`
* **Interface Description**: Executes a query and returns the first column of the first row in the query result.
* **Return Value**: The first column of the first row in the query result.
* **Exception**: Throws `TDengineError` exception on execution failure.
* `public DbDataReader ExecuteReader()`
* **Interface Description**: Executes a query and returns a data reader for the query results.
* **Return Value**: Data reader for the query results.
* **Exception**: Throws `TDengineError` exception on execution failure.
* `public void Dispose();`
* **Interface Description**: Releases resources.
#### Extended Interface
The extended interface is mainly used for request link tracking.
* `IRows Query(string query, long reqId)`
* **Interface Description**: Executes a query and returns the query results.
* **Parameter Description**:
* `query`: Query statement.
* `reqId`: Request ID.
* **Return Value**: Query results.
* **Exception**: Throws `TDengineError` exception on execution failure.
* `long Exec(string query, long reqId)`
* **Interface Description**: Executes an SQL statement.
* **Parameter Description**:
* `query`: SQL statement.
* `reqId`: Request ID.
* **Return Value**: Number of rows affected.
* **Exception**: Throws `TDengineError` exception on execution failure.
### Result Retrieval
The C# driver provides a `DbDataReader` interface that complies with the ADO.NET standard, offering methods to read metadata and data from the result set.
#### Result Set
The `DbDataReader` interface provides the following methods to retrieve the result set:
* `public bool GetBoolean(int ordinal)`
* **Interface Description**: Gets the boolean value of a specified column.
* **Parameter Description**:
* `ordinal`: Column index.
* **Return Value**: Boolean value.
* **Exception**: Throws `InvalidCastException` exception if types do not match.
* `public byte GetByte(int ordinal)`
* **Interface Description**: Gets the byte value of a specified column.
* **Parameter Description**:
* `ordinal`: Column index.
* **Return Value**: Byte value.
* **Exception**: Throws `InvalidCastException` exception if types do not match.
* `public long GetBytes(int ordinal, long dataOffset, byte[] buffer, int bufferOffset, int length)`
* **Interface Description**: Gets the byte value of a specified column.
* **Parameter Description**:
* `ordinal`: Column index.
* `dataOffset`: Data offset.
* `buffer`: Buffer.
* `bufferOffset`: Buffer offset.
* `length`: Length.
* **Return Value**: Byte value.
* **Exception**: Throws `InvalidCastException` exception if types do not match.
* `public char GetChar(int ordinal)`
* **Interface Description**: Gets the character value of the specified column.
* **Parameter Description**:
* `ordinal`: Column index.
* **Return Value**: Character value.
* **Exception**: Throws `InvalidCastException` if the type does not correspond.
* `public long GetChars(int ordinal, long dataOffset, char[] buffer, int bufferOffset, int length)`
* **Interface Description**: Gets the character value of the specified column.
* **Parameter Description**:
* `ordinal`: Column index.
* `dataOffset`: Data offset.
* `buffer`: Buffer.
* `bufferOffset`: Buffer offset.
* `length`: Length.
* **Return Value**: Character value.
* **Exception**: Throws `InvalidCastException` if the type does not correspond.
* `public DateTime GetDateTime(int ordinal)`
* **Interface Description**: Gets the date and time value of the specified column.
* **Parameter Description**:
* `ordinal`: Column index.
* **Return Value**: Date and time value.
* **Exception**: Throws `InvalidCastException` if the type does not correspond.
* `public double GetDouble(int ordinal)`
* **Interface Description**: Gets the double precision floating-point value of the specified column.
* **Parameter Description**:
* `ordinal`: Column index.
* **Return Value**: Double precision floating-point value.
* **Exception**: Throws `InvalidCastException` if the type does not correspond.
* `public float GetFloat(int ordinal)`
* **Interface Description**: Gets the single precision floating-point value of the specified column.
* **Parameter Description**:
* `ordinal`: Column index.
* **Return Value**: Single precision floating-point value.
* **Exception**: Throws `InvalidCastException` if the type does not correspond.
* `public short GetInt16(int ordinal)`
* **Interface Description**: Gets the 16-bit integer value of the specified column.
* **Parameter Description**:
* `ordinal`: Column index.
* **Return Value**: 16-bit integer value.
* **Exception**: Throws `InvalidCastException` if the type does not correspond.
* `public int GetInt32(int ordinal)`
* **Interface Description**: Gets the 32-bit integer value of the specified column.
* **Parameter Description**:
* `ordinal`: Column index.
* **Return Value**: 32-bit integer value.
* **Exception**: Throws `InvalidCastException` if the type does not correspond.
* `public long GetInt64(int ordinal)`
* **Interface Description**: Gets the 64-bit integer value of the specified column.
* **Parameter Description**:
* `ordinal`: Column index.
* **Return Value**: 64-bit integer value.
* **Exception**: Throws `InvalidCastException` if the type does not correspond.
* `public string GetString(int ordinal)`
* **Interface Description**: Gets the string value of the specified column.
* **Parameter Description**:
* `ordinal`: Column index.
* **Return Value**: String value.
* **Exception**: Throws `InvalidCastException` if the type does not correspond.
* `public object GetValue(int ordinal)`
* **Interface Description**: Gets the value of the specified column.
* **Parameter Description**:
* `ordinal`: Column index.
* **Return Value**: Result object.
* `public int GetValues(object[] values)`
* **Interface Description**: Gets the values of all columns.
* **Parameter Description**:
* `values`: Array of values.
* **Return Value**: Number of values.
* `public bool IsDBNull(int ordinal)`
* **Interface Description**: Determines if the specified column is NULL.
* **Parameter Description**:
* `ordinal`: Column index.
* **Return Value**: Whether it is NULL.
* `public int RecordsAffected`
* **Interface Description**: Gets the number of affected rows.
* **Return Value**: Number of affected rows.
* `public bool HasRows`
* **Interface Description**: Whether the result has row data.
* **Return Value**: Whether the result has row data.
* `public bool Read()`
* **Interface Description**: Reads the next row.
* **Return Value**: Whether the read was successful.
* `public IEnumerator GetEnumerator()`
* **Interface Description**: Gets the enumerator.
* **Return Value**: Enumerator.
* `public void Close()`
* **Interface Description**: Closes the result set.
#### Result Set Metadata
The `DbDataReader` interface provides the following methods to obtain result set metadata:
* `public DataTable GetSchemaTable()`
* **Interface Description**: Gets the result set metadata.
* **Return Value**: Result set metadata.
* `public string GetDataTypeName(int ordinal)`
* **Interface Description**: Gets the data type name of the specified column.
* **Parameter Description**:
* `ordinal`: Column index.
* **Return Value**: Data type name.
* `public Type GetFieldType(int ordinal)`
* **Interface Description**: Gets the data type of the specified column.
* **Parameter Description**:
* `ordinal`: Column index.
* **Return Value**: Data type.
* `public string GetName(int ordinal)`
* **Interface Description**: Gets the name of the specified column.
* **Parameter Description**:
* `ordinal`: Column index.
* **Return Value**: Column name.
* `public int GetFieldSize(int ordinal)`
* **Interface Description**: Gets the size of the specified column.
* **Parameter Description**:
* `ordinal`: Column index.
* **Return Value**: Column size.
* `public int GetOrdinal(string name)`
* **Interface Description**: Gets the index of the specified column.
* **Parameter Description**:
* `name`: Column name.
* **Return Value**: Column index.
* `public int FieldCount`
* **Interface Description**: Gets the number of columns.
* **Return Value**: Number of columns.
### Parameter Binding
The `TDengineCommand` class supports parameter binding.
#### Standard Interface
The `TDengineCommand` class inherits the `DbCommand` interface, supporting the following features:
* `public string CommandText`
* **Interface Description**: Gets or sets the command text, supports parameter binding.
* **Return Value**: Command text.
* `public new virtual TDengineParameterCollection Parameters`
* **Interface Description**: Gets the parameter collection.
* **Return Value**: `TDengineParameterCollection` object.
#### Parameter Metadata
The `TDengineParameterCollection` inherits the `DbParameterCollection` interface, supporting the following features:
* `public int Add(object value)`
* **Interface Description**: Adds a parameter.
* **Parameter Description**:
* `value`: Parameter value.
* **Return Value**: Parameter index.
* `public void Clear()`
* **Interface Description**: Clears parameters.
* `public bool Contains(object value)`
* **Interface Description**: Whether it contains a parameter.
* **Parameter Description**:
* `value`: Parameter value.
* **Return Value**: Whether it contains the parameter.
* `public int IndexOf(object value)`
* **Interface Description**: Get the parameter index.
* **Parameter Description**:
* `value`: Parameter value.
* **Return Value**: Parameter index.
* `public void Insert(int index, object value)`
* **Interface Description**: Insert a parameter.
* **Parameter Description**:
* `index`: Index.
* `value`: Parameter value.
* `public void Remove(object value)`
* **Interface Description**: Remove a parameter.
* **Parameter Description**:
* `value`: Parameter value.
* `public void RemoveAt(int index)`
* **Interface Description**: Remove a parameter.
* **Parameter Description**:
* `index`: Index.
* `public void RemoveAt(string parameterName)`
* **Interface Description**: Remove a parameter.
* **Parameter Description**:
* `parameterName`: Parameter name.
* `public int Count`
* **Interface Description**: Get the count of parameters.
* **Return Value**: Number of parameters.
* `public int IndexOf(string parameterName)`
* **Interface Description**: Get the parameter index.
* **Parameter Description**:
* `parameterName`: Parameter name.
* **Return Value**: Parameter index.
* `public bool Contains(string value)`
* **Interface Description**: Check if a parameter is included.
* **Parameter Description**:
* `value`: Parameter name.
* **Return Value**: Whether the parameter is included.
* `public void CopyTo(Array array, int index)`
* **Interface Description**: Copy parameters.
* **Parameter Description**:
* `array`: Target array.
* `index`: Index.
* `public IEnumerator GetEnumerator()`
* **Interface Description**: Get an enumerator.
* **Return Value**: Enumerator.
* `public void AddRange(Array values)`
* **Interface Description**: Add parameters.
* **Parameter Description**:
* `values`: Array of parameters.
`TDengineParameter` inherits from the `DbParameter` interface, supporting the following functionalities:
* `public TDengineParameter(string name, object value)`
* **Interface Description**: TDengineParameter constructor.
* **Parameter Description**:
* `name`: Parameter name, must start with @, such as @0, @1, @2, etc.
* `value`: Parameter value, must correspond one-to-one with C# column types and TDengine column types.
* `public string ParameterName`
* **Interface Description**: Get or set the parameter name.
* **Return Value**: Parameter name.
* `public object Value`
* **Interface Description**: Get or set the parameter value.
* **Return Value**: Parameter value.
#### Extended Interface
`ITDengineClient` interface provides an extended parameter binding interface.
* `IStmt StmtInit(long reqId)`
* **Interface Description**: Initialize a statement object.
* **Parameter Description**:
* `reqId`: Request ID.
* **Return Value**: Object implementing the IStmt interface.
* **Exception**: Throws `TDengineError` exception on failure.
`IStmt` interface provides an extended parameter binding interface.
* `void Prepare(string query)`
* **Interface Description**: Prepare a statement.
* **Parameter Description**:
* `query`: Query statement.
* **Exception**: Throws `TDengineError` exception on failure.
* `bool IsInsert()`
* **Interface Description**: Determines whether it is an insert statement.
* **Return Value**: Whether it is an insert statement.
* **Exception**: Throws `TDengineError` exception on execution failure.
* `void SetTableName(string tableName)`
* **Interface Description**: Sets the table name.
* **Parameter Description**:
* `tableName`: Table name.
* **Exception**: Throws `TDengineError` exception on execution failure.
* `void SetTags(object[] tags)`
* **Interface Description**: Sets tags.
* **Parameter Description**:
* `tags`: Array of tags.
* **Exception**: Throws `TDengineError` exception on execution failure.
* `TaosFieldE[] GetTagFields()`
* **Interface Description**: Gets tag attributes.
* **Return Value**: Array of tag attributes.
* **Exception**: Throws `TDengineError` exception on execution failure.
* `TaosFieldE[] GetColFields()`
* **Interface Description**: Gets column attributes.
* **Return Value**: Array of column attributes.
* **Exception**: Throws `TDengineError` exception on execution failure.
* `void BindRow(object[] row)`
* **Interface Description**: Binds a row.
* **Parameter Description**:
* `row`: Array of row data.
* **Exception**: Throws `TDengineError` exception on execution failure.
* `void BindColumn(TaosFieldE[] fields, params Array[] arrays)`
* **Interface Description**: Binds all columns.
* **Parameter Description**:
* `fields`: Array of field attributes.
* `arrays`: Arrays of multiple column data.
* **Exception**: Throws `TDengineError` exception on execution failure.
* `void AddBatch()`
* **Interface Description**: Adds a batch.
* **Exception**: Throws `TDengineError` exception on execution failure.
* `void Exec()`
* **Interface Description**: Executes parameter binding.
* **Exception**: Throws `TDengineError` exception on execution failure.
* `long Affected()`
* **Interface Description**: Gets the number of affected rows.
* **Return Value**: Number of affected rows.
* **Exception**: Throws `TDengineError` exception on execution failure.
* `IRows Result()`
* **Interface Description**: Gets the result.
* **Return Value**: Result object.
* **Exception**: Throws `TDengineError` exception on execution failure.
### Data Subscription
The `ConsumerBuilder` class provides interfaces related to consumer building, the `ConsumeResult` class provides interfaces related to consumption results, and the `TopicPartitionOffset` class provides interfaces related to partition offsets. `ReferenceDeserializer` and `DictionaryDeserializer` provide support for deserialization.
#### Consumer
* `public ConsumerBuilder(IEnumerable<KeyValuePair<string, string>> config)`
* **Interface Description**: ConsumerBuilder constructor.
* **Parameter Description**:
* `config`: Consumption configuration.
Supported properties for creating consumers:
* `useSSL`: Whether to use SSL connection, default is false.
* `token`: Token for connecting to TDengine cloud.
* `ws.message.enableCompression`: Whether to enable WebSocket compression, default is false.
* `ws.autoReconnect`: Whether to automatically reconnect, default is false.
* `ws.reconnect.retry.count`: Number of reconnection attempts, default is 3.
* `ws.reconnect.interval.ms`: Reconnection interval in milliseconds, default is 2000.
For other parameters, please refer to: [Consumer Parameter List](../../../developer-guide/manage-consumers/), note that the default value of auto.offset.reset in message subscription has changed starting from TDengine server version 3.2.0.0.
* `public IConsumer<TValue> Build()`
* **Interface Description**: Build the consumer.
* **Return Value**: Consumer object.
`IConsumer` interface provides the following consumer-related APIs:
* `ConsumeResult<TValue> Consume(int millisecondsTimeout)`
* **Interface Description**: Consume messages.
* **Parameter Description**:
* `millisecondsTimeout`: Timeout in milliseconds.
* **Return Value**: Consumption result.
* **Exception**: Throws `TDengineError` exception on failure.
* `List<TopicPartition> Assignment { get; }`
* **Interface Description**: Get assignment information.
* **Return Value**: Assignment information.
* **Exception**: Throws `TDengineError` exception on failure.
* `List<string> Subscription()`
* **Interface Description**: Get subscribed topics.
* **Return Value**: List of topics.
* **Exception**: Throws `TDengineError` exception on failure.
* `void Subscribe(IEnumerable<string> topic)`
* **Interface Description**: Subscribe to a list of topics.
* **Parameter Description**:
* `topic`: List of topics.
* **Exception**: Throws `TDengineError` exception on failure.
* `void Subscribe(string topic)`
* **Interface Description**: Subscribe to a single topic.
* **Parameter Description**:
* `topic`: Topic.
* **Exception**: Throws `TDengineError` exception on failure.
* `void Unsubscribe()`
* **Interface Description**: Unsubscribe.
* **Exception**: Throws `TDengineError` exception on failure.
* `void Commit(ConsumeResult<TValue> consumerResult)`
* **Interface Description**: Commit consumption result.
* **Parameter Description**:
* `consumerResult`: Consumption result.
* **Exception**: Throws `TDengineError` exception on failure.
* `List<TopicPartitionOffset> Commit()`
* **Interface Description**: Commit all consumption results.
* **Return Value**: Partition offsets.
* **Exception**: Throws `TDengineError` exception on failure.
* `void Commit(IEnumerable<TopicPartitionOffset> offsets)`
* **Interface Description**: Commit consumption results.
* **Parameter Description**:
* `offsets`: Partition offsets.
* **Exception**: Throws `TDengineError` exception on failure.
* `void Seek(TopicPartitionOffset tpo)`
* **Interface Description**: Jump to partition offset.
* **Parameter Description**:
* `tpo`: Partition offset.
* **Exception**: Throws `TDengineError` exception on failure.
* `List<TopicPartitionOffset> Committed(TimeSpan timeout)`
* **Interface Description**: Get partition offsets.
* **Parameter Description**:
* `timeout`: Timeout (unused).
* **Return Value**: Partition offsets.
* **Exception**: Throws `TDengineError` exception on failure.
* `List<TopicPartitionOffset> Committed(IEnumerable<TopicPartition> partitions, TimeSpan timeout)`
* **Interface Description**: Get specified partition offsets.
* **Parameter Description**:
* `partitions`: List of partitions.
* `timeout`: Timeout (unused).
* **Return Value**: Partition offsets.
* **Exception**: Throws `TDengineError` exception on failure.
* `Offset Position(TopicPartition partition)`
* **Interface Description**: Get the consumption position.
* **Parameter Description**:
* `partition`: Partition.
* **Return Value**: Offset.
* **Exception**: Throws `TDengineError` exception if execution fails.
* `void Close()`
* **Interface Description**: Close the consumer.
#### Consumption Record
`ConsumeResult` class provides interfaces related to consumption results:
* `public List<TmqMessage<TValue>> Message`
* **Interface Description**: Get the list of messages.
* **Return Value**: List of messages.
`TmqMessage` class provides the specific content of messages:
```csharp
public class TmqMessage<TValue>
{
public string TableName { get; set; }
public TValue Value { get; set; }
}
```
* `TableName`: Table name
* `Value`: Message content
#### Partition Information
Get `TopicPartitionOffset` from `ConsumeResult`:
```csharp
public TopicPartitionOffset TopicPartitionOffset
```
`TopicPartitionOffset` class provides interfaces for getting partition information:
* `public string Topic { get; }`
* **Interface Description**: Get the topic.
* **Return Value**: Topic.
* `public Partition Partition { get; }`
* **Interface Description**: Get the partition.
* **Return Value**: Partition.
* `public Offset Offset { get; }`
* **Interface Description**: Get the offset.
* **Return Value**: Offset.
* `public TopicPartition TopicPartition`
* **Interface Description**: Get the topic partition.
* **Return Value**: Topic partition.
* `public string ToString()`
* **Interface Description**: Convert to string.
* **Return Value**: String information.
#### Offset Metadata
`Offset` class provides interfaces related to offset:
* `public long Value`
* **Interface Description**: Get the offset value.
* **Return Value**: Offset value.
#### Deserialization
The C# driver provides two deserialization classes: `ReferenceDeserializer` and `DictionaryDeserializer`. Both implement the `IDeserializer` interface.
ReferenceDeserializer is used to deserialize a consumed record into an object, ensuring that the object class's property names correspond to the consumed data's column names and that the types match.
DictionaryDeserializer will deserialize a consumed row of data into a `Dictionary<string, object>` object, where the key is the column name and the value is the object.
Interfaces of ReferenceDeserializer and DictionaryDeserializer are not directly called by users, please refer to the usage examples.
## Appendix
[More example programs](https://github.com/taosdata/taos-connector-dotnet/tree/3.0/examples).