AddRecordByNameValueAsync

Part of the IQSDataTable interface, this method inserts a new record using a NameValueCollection, a common .NET container for key‑value pairs. Under the hood it converts the collection into a dictionary and then inserts the record.

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 name/value collection. Each key in the collection 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 dictionary‑based method: the operation can be executed immediately or added to a batch queue identified by BatchId. The return value indicates the number of rows affected (immediate mode) or 1 (queued mode).

Signature

public async Task<int> AddRecordByNameValueAsync(NameValueCollection record, Guid BatchId, bool ImmediateAction = false)

Parameters

NameTypeDescription
recordNameValueCollection A collection of string‑key/string‑value pairs representing the column names and their data for the new record.
BatchIdGuid A unique identifier for the batch. When ImmediateAction is false, the insert is added to the execution queue for this batch.
ImmediateActionbool (optional, default false) If true the insert is executed immediately against the database; if false (default) the statement is queued.

Returns

A Task<int> representing the asynchronous operation.

  • Immediate mode: the number of affected rows (typically 1 on success).
  • Queued mode: returns 1 indicating the query was successfully added to the batch queue.

Example Usage

// Define the data table
IQSDataTable productsTable = QSAppContext.Tables["Products"];

// Build the record as a NameValueCollection
NameValueCollection newProduct = new NameValueCollection();
newProduct.Add("Id", Guid.NewGuid().ToString());
newProduct.Add("ProductName", "Wireless Mouse");
newProduct.Add("Price", "29.99");
newProduct.Add("Stock", "150");

Guid batchId = Guid.NewGuid();

// Queue the insert (default behavior)
int queuedResult = await productsTable.AddRecordByNameValueAsync(newProduct, batchId);

// Execute immediately
int affectedRows = await productsTable.AddRecordByNameValueAsync(newProduct, batchId, true);

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