AddRecordByDictionaryAsync

Part of the IQSDataTable interface, this method inserts a new record into the data source. Values are supplied as a dictionary mapping column names to their values, making it flexible and easy to build dynamic inserts.

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 dictionary. Each key in the dictionary corresponds to a column name, and its value is the data to be inserted into that column. The method handles the serialisation of 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 behaviour follows the same insert logic as the name/value‑based method: The operation can either be executed immediately or added to a batch execution queue. When queued, it is linked to a BatchId so that multiple operations can be committed together later. The method returns 1 for a successful queued operation, or the number of affected rows if executed immediately.

Signature

public async Task<int> AddRecordByDictionaryAsync(Dictionary<string, object?> record, Guid BatchId, bool ImmediateAction = false)

Parameters

NameTypeDescription
recordDictionary<string, object?> A dictionary where each key is a column name and the value is the data for that column. Values can be of any type; they will be serialised into the generated SQL insert statement.
BatchIdGuid A unique identifier for the batch. When ImmediateAction is false, the generated SQL is added to an execution queue associated with this batch.
ImmediateActionbool (optional, default false) If true, the insert is executed against the database immediately. If false (the default), the statement is added to the batch queue and the method returns 1.

Returns

A Task<int> representing the asynchronous operation.

  • When ImmediateAction is true, the return value is the number of rows affected (typically 1 if the insert succeeded, 0 otherwise).
  • When ImmediateAction is false, the method returns 1 to indicate the query was successfully added to the execution queue.

Example Usage

// Define the data table
IQSDataTable customersTable = QSAppContext.Tables["Customers"];

// Build the record dictionary
Dictionary<string, object?> newCustomer = new()
{
    { "Id", Guid.NewGuid().ToString() },
    { "Name", "Jane Doe" },
    { "Email", "jane.doe@example.com" },
    { "Phone", "+123456789" }
};

Guid batchId = Guid.NewGuid();

// 1. Queue the insert (ImmediateAction = false, default)
int queuedResult = await customersTable.AddRecordByDictionaryAsync(newCustomer, batchId);

// 2. Execute immediately
int affectedRows = await customersTable.AddRecordByDictionaryAsync(newCustomer, batchId, true);

Console.WriteLine($"Queued: {queuedResult}, Immediate: {affectedRows}");