xxq250
/
homework-jianmu
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
homework-jianmu/docs/en/14-reference/05-connector/40-csharp.mdx

817 lines
33 KiB
Plaintext
Raw Blame History

---
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 "./_request_id.mdx";
`TDengine.Connector` is the C# connector provided by TDengine, allowing C# developers to create applications that access TDengine cluster data.
## Connection Methods
`TDengine.Connector` provides two types of connectors:
- **Native Connection**: Connects to the TDengine instance using the TDengine client driver (taosc), supporting data writing, querying, data subscription, schemaless interfaces, and parameter binding interfaces.
- **WebSocket Connection**: Connects to the TDengine instance through the WebSocket interface provided by taosAdapter, with some differences in functionality compared to the native connection (available since v3.0.1).
For detailed introductions to connection methods, please refer to: [Connecting to TDengine](../../../developer-guide/connecting-to-tdengine/).
## Compatibility
- Version 3.1.0 of `TDengine.Connector` underwent a complete refactoring and is not compatible with versions 3.0.2 and earlier. For documentation on 3.0.2, please refer to [nuget](https://www.nuget.org/packages/TDengine.Connector/3.0.2).
- `TDengine.Connector` 3.x is not compatible with TDengine 2.x. If you are running in an environment with TDengine 2.x, please use version 1.x of TDengine.Connector.
## Supported Platforms
The supported platforms are consistent with those of the TDengine client driver.
:::warning
TDengine no longer supports 32-bit Windows platforms.
:::
## Version Support
| **Connector Version** | **TDengine Version** | **Main Features** |
|-----------------------|-----------------------|-------------------------------------|
| 3.1.3 | 3.2.1.0/3.1.1.18 | Supports WebSocket automatic reconnection |
| 3.1.2 | 3.2.1.0/3.1.1.18 | Fixes schemaless resource release |
| 3.1.1 | 3.2.1.0/3.1.1.18 | Supports varbinary and geometry types|
| 3.1.0 | 3.2.1.0/3.1.1.18 | WebSocket uses native implementation |
## Exception Handling
`TDengine.Connector` throws exceptions that applications need to handle. The taosc exception type is `TDengineError`, which includes error codes and messages, allowing applications to handle them based on the codes and messages.
For errors from 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 (UTF-8) |
| JSON | byte[] |
| VARBINARY | byte[] |
| GEOMETRY | byte[] |
**Note**: The JSON type is only supported in tags.
The GEOMETRY type is little-endian binary data conforming to the WKB specification. For more details, refer to [Data Types](../../sql-manual/data-types/).
For WKB specification, please refer to [Well-Known Binary (WKB)](https://libgeos.org/specifications/wkb/).
## Example Programs Summary
Please refer to the [Example Programs](https://github.com/taosdata/taos-connector-dotnet/tree/3.0/examples) for example program source code.
## 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 Specification
The ConnectionStringBuilder sets connection parameters using a key-value format, 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`: The address of the TDengine instance.
- `port`: The port of the TDengine instance.
- `username`: The username for the connection.
- `password`: The password for the connection.
- `protocol`: The connection protocol; optional values are Native or WebSocket, defaulting to Native.
- `db`: The database for the connection.
- `timezone`: The timezone, defaulting to the local timezone.
##### 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`: The address of the TDengine instance.
- `port`: The port of the TDengine instance.
- `username`: The username for the connection.
- `password`: The password for the connection.
- `protocol`: The connection protocol; optional values are Native or WebSocket, defaulting to Native.
- `db`: The database for the connection.
- `timezone`: The timezone, defaulting to the local timezone.
- `connTimeout`: Connection timeout, defaulting to 1 minute.
- `readTimeout`: Read timeout, defaulting to 5 minutes.
- `writeTimeout`: Write timeout, defaulting to 10 seconds.
- `token`: The token for connecting to TDengine cloud.
- `useSSL`: Whether to use SSL for the connection, defaulting to false.
- `enableCompression`: Whether to enable WebSocket compression, defaulting to false.
- `autoReconnect`: Whether to automatically reconnect, defaulting to false.
- `reconnectRetryCount`: Number of reconnection attempts, defaulting to 3.
- `reconnectIntervalMs`: Reconnection interval in milliseconds, defaulting to 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`: The connection configuration string.
### Connection Functionality
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 schemaless writing interfaces.
#### Standard Interfaces
The ADO.NET connection supports the following standard interfaces:
- `public TDengineConnection(string connectionString)`
- **Interface Description**: Constructor for TDengineConnection.
- **Parameter Description**:
- `connectionString`: The connection configuration string.
- **Exception**: Throws `ArgumentException` if the format is incorrect.
- `public void ChangeDatabase(string databaseName)`
- **Interface Description**: Changes the database.
- **Parameter Description**:
- `databaseName`: The database name.
- **Exception**: Throws `TDengineError` if the execution fails.
- `public void Close()`
- **Interface Description**: Closes the connection.
- `public void Open()`
- **Interface Description**: Opens the connection.
- **Exception**: Throws `TDengineError` if the opening fails; WebSocket connections may experience network exceptions that should be handled.
- `public string ServerVersion`
- **Interface Description**: Returns the server version.
- **Return Value**: The server version string.
- **Exception**: Throws `TDengineError` if the execution fails.
- `public string DataSource`
- **Interface Description**: Returns the data source.
- **Return Value**: Host configuration of the created connection.
- `public string Database`
- **Interface Description**: Returns the connected database.
- **Return Value**: The database configured for the created connection.
- `public TDengineCommand(TDengineConnection connection)`
- **Interface Description**: Constructor for TDengineCommand.
- **Parameter Description**:
- `connection`: TDengineConnection object.
- **Exception**: Throws `TDengineError` if the execution fails.
- `public void Prepare()`
- **Interface Description**: Checks the connection and command text and prepares the command for execution.
- **Exception**: Throws `InvalidOperationException` if open has not been executed or CommandText has not been set.
- `public string CommandText`
- **Interface Description**: Gets or sets the command text.
- **Return Value**: The 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**: Opens the connection.
- **Parameter Description**:
- `builder`: Connection configuration.
- **Return Value**: ITDengineClient interface.
- **Exception**: Throws `TDengineError` if the opening fails; WebSocket connections may experience network exceptions that should be handled.
- `void SchemalessInsert(string[] lines, TDengineSchemalessProtocol protocol, TDengineSchemalessPrecision precision, int ttl, long reqId)`
- **Interface Description**: Performs schemaless writing.
- **Parameter Description**:
- `lines`: Array of data lines.
- `protocol`: Data protocol, supporting protocols: `TSDB_SML_LINE_PROTOCOL = 1`, `TSDB_SML_TELNET_PROTOCOL = 2`, `TSDB_SML_JSON_PROTOCOL = 3`.
- `precision`: Time precision, supporting 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, where 0 means not configured.
- `reqId`: Request ID.
- **Exception**: Throws `TDengineError` if the execution fails.
### Execute SQL
The C# driver provides a `DbCommand` interface compliant with ADO.NET standards, supporting the following features:
1. **Execute SQL Statements**: Execute static SQL statements and return their result objects.
2. **Query Execution**: Can execute queries that return datasets (SELECT statements).
3. **Update Execution**: Can execute SQL statements that affect row counts, such as INSERT, UPDATE, DELETE, etc.
4. **Get Results**: Can retrieve the result sets returned by query executions (ResultSet objects) and iterate through the returned data.
5. **Get Update Count**: For non-query SQL statements, can retrieve the number of affected rows after execution.
6. **Release Resources**: Provides a method to close and release database resources.
Additionally, the C# driver provides extended interfaces for request tracing.
#### Standard Interfaces
- `public int ExecuteNonQuery()`
- **Interface Description**: Executes an SQL statement and returns the number of affected rows.
- **Return Value**: The number of affected rows.
- **Exception**: Throws `TDengineError` if execution fails.
- `public object ExecuteScalar()`
- **Interface Description**: Executes a query and returns the first row of the first column of the result.
- **Return Value**: The first row of the first column of the query result.
- **Exception**: Throws `TDengineError` if execution fails.
- `public DbDataReader ExecuteReader()`
- **Interface Description**: Executes a query and returns a data reader for the query result.
- **Return Value**: The data reader for the query result.
- **Exception**: Throws `TDengineError` if execution fails.
- `public void Dispose();`
- **Interface Description**: Releases resources.
#### Extended Interfaces
The extended interfaces are mainly used for request tracing.
- `IRows Query(string query, long reqId)`
- **Interface Description**: Executes a query and returns the result.
- **Parameter Description**:
- `query`: The query statement.
- `reqId`: Request ID.
- **Return Value**: The query result.
- **Exception**: Throws `TDengineError` if execution fails.
- `long Exec(string query, long reqId)`
- **Interface Description**: Executes an SQL statement.
- **Parameter Description**:
- `query`: SQL statement.
- `reqId`: Request ID.
- **Return Value**: The number of affected rows.
- **Exception**: Throws `TDengineError` if execution fails.
### Result Retrieval
The C# driver provides a `DbDataReader` interface compliant with ADO.NET standards, offering methods for reading metadata and data from result sets.
#### Result Set
The `DbDataReader` interface provides the following methods to retrieve result sets:
- `public bool GetBoolean(int ordinal)`
- **Interface Description**: Gets the boolean value of the specified column.
- **Parameter Description**:
- `ordinal`: Column index.
- **Return Value**: The boolean value.
- **Exception**: Throws `InvalidCastException` if the type does not match.
- `public byte GetByte(int ordinal)`
- **Interface Description**: Gets the byte value of the specified column.
- **Parameter Description**:
- `ordinal`: Column index.
- **Return Value**: The byte value.
- **Exception**: Throws `InvalidCastException` if the type does not match.
- `public long GetBytes(int ordinal, long dataOffset, byte[] buffer, int bufferOffset, int length)`
- **Interface Description**: Gets the byte value of the specified column.
- **Parameter Description**:
- `ordinal`: Column index.
- `dataOffset`: Data offset.
- `buffer`: Buffer.
- `bufferOffset`: Buffer offset.
- `length`: Length.
- **Return Value**: The byte value.
- **Exception**: Throws `InvalidCastException` if the type does not match.
- `public char GetChar(int ordinal)`
- **Interface Description**: Gets the character value of the specified column.
- **Parameter Description**:
- `ordinal`: Column index.
- **Return Value**: The character value.
- **Exception**: Throws `InvalidCastException` if the type does not match.
- `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**: The character value.
- **Exception**: Throws `InvalidCastException` if the type does not match.
- `public DateTime GetDateTime(int ordinal)`
- **Interface Description**: Gets the DateTime value of the specified column.
- **Parameter Description**:
- `ordinal`: Column index.
- **Return Value**: The DateTime value.
- **Exception**: Throws `InvalidCastException` if the type does not match.
- `public double GetDouble(int ordinal)`
- **Interface Description**: Gets the double value of the specified column.
- **Parameter Description**:
- `ordinal`: Column index.
- **Return Value**: The double value.
- **Exception**: Throws `InvalidCastException` if the type does not match.
- `public float GetFloat(int ordinal)`
- **Interface Description**: Gets the float value of the specified column.
- **Parameter Description**:
- `ordinal`: Column index.
- **Return Value**: The float value.
- **Exception**: Throws `InvalidCastException` if the type does not match.
- `public short GetInt16(int ordinal)`
- **Interface Description**: Gets the 16-bit integer value of the specified column.
- **Parameter Description**:
- `ordinal`: Column index.
- **Return Value**: The 16-bit integer value.
- **Exception**: Throws `InvalidCastException` if the type does not match.
- `public int GetInt32(int ordinal)`
- **Interface Description**: Gets the 32-bit integer value of the specified column.
- **Parameter Description**:
- `ordinal`: Column index.
- **Return Value**: The 32-bit integer value.
- **Exception**: Throws `InvalidCastException` if the type does not match.
- `public long GetInt64(int ordinal)`
- **Interface Description**: Gets the 64-bit integer value of the specified column.
- **Parameter Description**:
- `ordinal`: Column index.
- **Return Value**: The 64-bit integer value.
- **Exception**: Throws `InvalidCastException` if the type does not match.
- `public string GetString(int ordinal)`
- **Interface Description**: Gets the string value of the specified column.
- **Parameter Description**:
- `ordinal`: Column index.
- **Return Value**: The string value.
- **Exception**: Throws `InvalidCastException` if the type does not match.
- `public object GetValue(int ordinal)`
- **Interface Description**: Gets the value of the specified column.
- **Parameter Description**:
- `ordinal`: Column index.
- **Return Value**: The result object.
- `public int GetValues(object[] values)`
- **Interface Description**: Gets the values of all columns.
- **Parameter Description**:
- `values`: The array of values.
- **Return Value**: The number of values.
- `public bool IsDBNull(int ordinal)`
- **Interface Description**: Checks 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**: The number of affected rows.
- `public bool HasRows`
- **Interface Description**: Checks if 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**: The enumerator.
- `public void Close()`
- **Interface Description**: Closes the result set.
#### Result Set Metadata
The `DbDataReader` interface provides the following methods for retrieving metadata from result sets:
- `public DataTable GetSchemaTable()`
- **Interface Description**: Gets the metadata for the result set.
- **Return Value**: The metadata for the result set.
- `public string GetDataTypeName(int ordinal)`
- **Interface Description**: Gets the data type name of the specified column.
- **Parameter Description**:
- `ordinal`: Column index.
- **Return Value**: The 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**: The data type.
- `public string GetName(int ordinal)`
- **Interface Description**: Gets the name of the specified column.
- **Parameter Description**:
- `ordinal`: Column index.
- **Return Value**: The column name.
- `public int GetFieldSize(int ordinal)`
- **Interface Description**: Gets the size of the specified column.
- **Parameter Description**:
- `ordinal`: Column index.
- **Return Value**: The column size.
- `public int GetOrdinal(string name)`
- **Interface Description**: Gets the index of the specified column.
- **Parameter Description**:
- `name`: Column name.
- **Return Value**: The column index.
- `public int FieldCount`
- **Interface Description**: Gets the number of columns.
- **Return Value**: The number of columns.
### Parameter Binding
The `TDengineCommand` class supports parameter binding.
#### Standard Interface
The `TDengineCommand` class inherits from the `DbCommand` interface and supports the following features:
- `public string CommandText`
- **Interface Description**: Gets or sets the command text, supporting parameter binding.
- **Return Value**: The command text.
- `public new virtual TDengineParameterCollection Parameters`
- **Interface Description**: Gets the parameter collection.
- **Return Value**: `TDengineParameterCollection` object.
#### Parameter Metadata
The `TDengineParameterCollection` inherits from the `DbParameterCollection` interface and supports the following features:
- `public int Add(object value)`
- **Interface Description**: Adds a parameter.
- **Parameter Description**:
- `value`: The parameter value.
- **Return Value**: The parameter index.
- `public void Clear()`
- **Interface Description**: Clears the parameters.
- `public bool Contains(object value)`
- **Interface Description**: Checks if the parameter exists.
- **Parameter Description**:
- `value`: The parameter value.
- **Return Value**: Whether the parameter exists.
- `public int IndexOf(object value)`
- **Interface Description**: Gets the parameter index.
- **Parameter Description**:
- `value`: The parameter value.
- **Return Value**: The parameter index.
- `public void Insert(int index, object value)`
- **Interface Description**: Inserts a parameter.
- **Parameter Description**:
- `index`: The index.
- `value`: The parameter value.
- `public void Remove(object value)`
- **Interface Description**: Removes a parameter.
- **Parameter Description**:
- `value`: The parameter value.
- `public void RemoveAt(int index)`
- **Interface Description**: Removes a parameter.
- **Parameter Description**:
- `index`: The index.
- `public void RemoveAt(string parameterName)`
- **Interface Description**: Removes a parameter.
- **Parameter Description**:
- `parameterName`: The parameter name.
- `public int Count`
- **Interface Description**: Gets the number of parameters.
- **Return Value**: The number of parameters.
- `public int IndexOf(string parameterName)`
- **Interface Description**: Gets the parameter index.
- **Parameter Description**:
- `parameterName`: The parameter name.
- **Return Value**: The parameter index.
- `public bool Contains(string value)`
- **Interface Description**: Checks if the parameter exists.
- **Parameter Description**:
- `value`: The parameter name.
- **Return Value**: Whether the parameter exists.
- `public void CopyTo(Array array, int index)`
- **Interface Description**: Copies parameters.
- **Parameter Description**:
- `array`: The target array.
- `index`: The index.
- `public IEnumerator GetEnumerator()`
- **Interface Description**: Gets the enumerator.
- **Return Value**: The enumerator.
- `public void AddRange(Array values)`
- **Interface Description**: Adds parameters.
- **Parameter Description**:
- `values`: The parameter array.
The `TDengineParameter` class inherits from the `DbParameter` interface and supports the following features:
- `public TDengineParameter(string name, object value)`
- **Interface Description**: `TDengineParameter` constructor.
- **Parameter Description**:
- `name`: The parameter name, which must start with @, such as @0, @1, @2, etc.
- `value`: The parameter value, which needs to match the C# column type with the TDengine column type.
- `public string ParameterName`
- **Interface Description**: Gets or sets the parameter name.
- **Return Value**: The parameter name.
- `public object Value`
- **Interface Description**: Gets or sets the parameter value.
- **Return Value**: The parameter value.
#### Extension Interfaces
The `ITDengineClient` interface provides extended parameter binding interfaces.
- `IStmt StmtInit(long reqId)`
- **Interface Description**: Initializes the statement object.
- **Parameter Description**:
- `reqId`: The request ID.
- **Return Value**: An object implementing the IStmt interface.
- **Exception**: Throws `TDengineError` exception on failure.
The `IStmt` interface provides extended parameter binding interfaces.
- `void Prepare(string query)`
- **Interface Description**: Prepares the statement.
- **Parameter Description**:
- `query`: The query statement.
- **Exception**: Throws `TDengineError` exception on failure.
- `bool IsInsert()`
- **Interface Description**: Determines if it is an insert statement.
- **Return Value**: Whether it is an insert statement.
- **Exception**: Throws `TDengineError` exception on failure.
- `void SetTableName(string tableName)`
- **Interface Description**: Sets the table name.
- **Parameter Description**:
- `tableName`: The table name.
- **Exception**: Throws `TDengineError` exception on failure.
- `void SetTags(object[] tags)`
- **Interface Description**: Sets the tags.
- **Parameter Description**:
- `tags`: The tags array.
- **Exception**: Throws `TDengineError` exception on failure.
- `TaosFieldE[] GetTagFields()`
- **Interface Description**: Gets the tag properties.
- **Return Value**: The tag properties array.
- **Exception**: Throws `TDengineError` exception on failure.
- `TaosFieldE[] GetColFields()`
- **Interface Description**: Gets the column properties.
- **Return Value**: The column properties array.
- **Exception**: Throws `TDengineError` exception on failure.
- `void BindRow(object[] row)`
- **Interface Description**: Binds a row.
- **Parameter Description**:
- `row`: The row data array.
- **Exception**: Throws `TDengineError` exception on failure.
- `void BindColumn(TaosFieldE[] fields, params Array[] arrays)`
- **Interface Description**: Binds all columns.
- **Parameter Description**:
- `fields`: The field properties array.
- `arrays`: The multi-column data array.
- **Exception**: Throws `TDengineError` exception on failure.
- `void AddBatch()`
- **Interface Description**: Adds a batch process.
- **Exception**: Throws `TDengineError` exception on failure.
- `void Exec()`
- **Interface Description**: Executes the parameter binding.
- **Exception**: Throws `TDengineError` exception on failure.
- `long Affected()`
- **Interface Description**: Gets the number of affected rows.
- **Return Value**: The number of affected rows.
- **Exception**: Throws `TDengineError` exception on failure.
- `IRows Result()`
- **Interface Description**: Gets the result.
- **Return Value**: The result object.
- **Exception**: Throws `TDengineError` exception on failure.
### Data Subscription
The `ConsumerBuilder` class provides interfaces related to building consumers, 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.
Creating the consumer support property list:
- `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 reconnections, default is 3.
- `ws.reconnect.interval.ms`: Reconnection interval in milliseconds, default is 2000.
For other parameters, please refer to: [Creating Parameters](../../../developer-guide/manage-consumers/#creating-parameters). Note that since TDengine server version 3.2.0.0, the default value of `auto.offset.reset` in message subscription has changed.
- `public IConsumer<TValue> Build()`
- **Interface Description**: Builds the consumer.
- **Return Value**: Consumer object.
The `IConsumer` interface provides consumer-related APIs:
- `ConsumeResult<TValue> Consume(int millisecondsTimeout)`
- **Interface Description**: Consumes messages.
- **Parameter Description**:
- `millisecondsTimeout`: Millisecond timeout.
- **Return Value**: Consumption result.
- **Exception**: Throws `TDengineError` exception on failure.
- `List<TopicPartition> Assignment { get; }`
- **Interface Description**: Gets the assignment information.
- **Return Value**: Assignment information.
- **Exception**: Throws `TDengineError` exception on failure.
- `List<string> Subscription()`
- **Interface Description**: Gets the subscribed topics.
- **Return Value**: Topic list.
- **Exception**: Throws `TDengineError` exception on failure.
- `void Subscribe(IEnumerable<string> topic)`
- **Interface Description**: Subscribes to the topic list.
- **Parameter Description**:
- `topic`: Topic list.
- **Exception**: Throws `TDengineError` exception on failure.
- `void Subscribe(string topic)`
- **Interface Description**: Subscribes to a single topic.
- **Parameter Description**:
- `topic`: Topic.
- **Exception**: Throws `TDengineError` exception on failure.
- `void Unsubscribe()`
- **Interface Description**: Unsubscribes.
- **Exception**: Throws `TDengineError` exception on failure.
- `void Commit(ConsumeResult<TValue> consumerResult)`
- **Interface Description**: Commits the consumption result.
- **Parameter Description**:
- `consumerResult`: Consumption result.
- **Exception**: Throws `TDengineError` exception on failure.
- `List<TopicPartitionOffset> Commit()`
- **Interface Description**: Commits all consumption results.
- **Return Value**: Partition offsets.
- **Exception**: Throws `TDengineError` exception on failure.
- `void Commit(IEnumerable<TopicPartitionOffset> offsets)`
- **Interface Description**: Commits consumption results.
- **Parameter Description**:
- `offsets`: Partition offsets.
- **Exception**: Throws `TDengineError` exception on failure.
- `void Seek(TopicPartitionOffset tpo)`
- **Interface Description**: Jumps to the partition offset.
- **Parameter Description**:
- `tpo`: Partition offset.
- **Exception**: Throws `TDengineError` exception on failure.
- `List<TopicPartitionOffset> Committed(TimeSpan timeout)`
- **Interface Description**: Gets the 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**: Gets the specified partition offsets.
- **Parameter Description**:
- `partitions`: Partition list.
- `timeout`: Timeout (unused).
- **Return Value**: Partition offsets.
- **Exception**: Throws `TDengineError` exception on failure.
- `Offset Position(TopicPartition partition)`
- **Interface Description**: Gets the consumption position.
- **Parameter Description**:
- `partition`: Partition.
- **Return Value**: Offset.
- **Exception**: Throws `TDengineError` exception on failure.
- `void Close()`
- **Interface Description**: Closes the consumer.
#### Consumption Records
The `ConsumeResult` class provides interfaces related to consumption results:
- `public List<TmqMessage<TValue>> Message`
- **Interface Description**: Gets the message list.
- **Return Value**: Message list.
The `TmqMessage` class provides the specific content of the message:
```csharp
public class TmqMessage<TValue>
{
public string TableName { get; set; }
public TValue Value { get; set; }
}
```
- `TableName`: The table name.
- `Value`: The message content.
#### Partition Information
From `ConsumeResult`, get `TopicPartitionOffset`:
```csharp
public TopicPartitionOffset TopicPartitionOffset
```
The `TopicPartitionOffset` class provides interfaces to get partition information:
- `public string Topic { get; }`
- **Interface Description**: Gets the topic.
- **Return Value**: The topic.
- `public Partition Partition { get; }`
- **Interface Description**: Gets the partition.
- **Return Value**: The partition.
- `public Offset Offset { get; }`
- **Interface Description**: Gets the offset.
- **Return Value**: The offset.
- `public TopicPartition TopicPartition`
- **Interface Description**: Gets the topic partition.
- **Return Value**: The topic partition.
- `public string ToString()`
- **Interface Description**: Converts to string.
- **Return Value**: String information.
#### Offset Metadata
The `Offset` class provides interfaces related to offsets:
- `public long Value`
- **Interface Description**: Gets the offset value.
- **Return Value**: The offset value.
#### Deserialization
The C# driver provides two deserialization classes: `ReferenceDeserializer` and `DictionaryDeserializer`. Both implement the `IDeserializer` interface.
The `ReferenceDeserializer` is used to deserialize a record consumed into an object, ensuring that the property names of the object class correspond to the column names of the consumed data and that the types match.
The `DictionaryDeserializer` deserializes a row of consumed data into a `Dictionary<string, object>` object, where the key is the column name and the value is the object.
The interfaces of `ReferenceDeserializer` and `DictionaryDeserializer` are not directly called by users; please refer to usage examples.
## Appendix
[More Example Programs](https://github.com/taosdata/taos-connector-dotnet/tree/3.0/examples).
Reference in New Issue View Git Blame Copy Permalink