AddRecordAsync
Part of the IQSDataTable interface, this method inserts a new record using newly created row IQSDataTableRow object using the IQSDataTable.CreateRowAsync() method. It automatically extracts the row’s fields to build the insert statement.
the (BatchId) is used to associate the added row, which is useful for tracking the added row and used later when calling SaveBatchAsync(BatchId) or SaveBatchOnlyAsync(BatchId) to determine which fields have been modified and apply the corresponding updates to the data source.
The method generates an SQL INSERT statement based on the provided IQSDataTableRow. The method handles the serialisation of field values into the appropriate SQL format.
You can choose to execute the insert immediately or add it to a batch for later execution. When added to a batch, the method returns 1 to indicate success, while immediate execution returns the number of affected rows.
The operation can be executed immediately or added to a batch queue keyed by BatchId. The return value indicates success: the number of affected rows for immediate execution, or 1 for queued mode.
Signature
public async Task<int> AddRecordAsync(IQSDataTableRow record, Guid BatchId, bool ImmediateAction = false)Parameters
| Name | Type | Description |
|---|---|---|
record | IQSDataTableRow | The row object containing the data to insert. The method extracts the field values from this object to construct the insert statement. |
BatchId | Guid | A unique identifier for the batch. When ImmediateAction is false, the generated SQL is queued under this batch. |
ImmediateAction | bool (optional, default false) | If true the insert is executed immediately; if false it is added to the batch execution queue. |
Returns
A Task<int> representing the asynchronous operation.
- Immediate mode: the number of rows affected by the insert (typically
1on success). - Queued mode: returns
1indicating the query was successfully added to the batch queue.
Example Usage
// Define the data table
IQSDataTable customersTable = QSAppContext.Tables["Customers"];
// An existing row object (could be from a previous query or manually created)
IQSDataTableRow _newRow = customersTable.CreateRowAsync();
_newRow["Id"] = Guid.NewGuid().ToString();
_newRow["Name"] = "John Smith";
_newRow["Email"] = "john.smith@example.com";
_newRow["Phone"] = "+987654321";
Guid batchId = Guid.NewGuid();
// Queue the insert (default)
int queuedResult = await customersTable.AddRecordAsync(_newRow, batchId);
// Execute immediately
int affectedRows = await customersTable.AddRecordAsync(_newRow, batchId, true);
Console.WriteLine($"Queued insert: {queuedResult}, Immediate insert: {affectedRows}");