GetRowByIdAsync

Part of the IQSDataTable interface, this method retrieves a single row from the data source as a strongly‑typed IQSDataTableRow object. It combines the unique identifier with a batch context (BatchId) to build a fully initialised row, including its fields.

the (BatchId) is used to associate the retrieved row with a logical group of operations, which is useful for tracking the fields modifications 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.

Asynchronously returns an IQSDataTableRow for the given Id, or null if no record is found. You can limit the columns returned by providing a comma‑separated list of target fields.

Data retrieved from this method can be modified and saved back to the data source using the appropriate save methods. The returned IQSDataTableRow is designed for edit operations, allowing you to change field values and track those changes within the context of the provided BatchId.

Signature

public async Task<IQSDataTableRow> GetRowByIdAsync(string Id, Guid BatchId, string TargetFields = "")

Parameters

NameTypeDescription
IdstringThe unique identifier of the row to fetch.
BatchIdGuid A batch identifier used to associate the retrieved row with a logical group of operations and track the row field changes in the resulting IQSDataTableRow.
TargetFieldsstring (optional) Comma‑separated column names to include in the underlying DataTable. If left empty (default), all columns are returned.

Returns

A Task<IQSDataTableRow> representing the asynchronous operation. The resulting IQSDataTableRow object is fully initialised with:

  • The table name and metadata (OwnerTableName, OwnerTableInfo)
  • The fetched DataRow
  • The provided BatchId

If no record matches the given Id, the method returns null.

Example Usage

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

// Unique ID and batch context
string recordId = "00000000-0000-0000-0000-000000000000";
Guid batchId = Guid.NewGuid();

// Retrieve a full row (all columns)
IQSDataTableRow row = await customersTable.GetRowByIdAsync(recordId, batchId);

// Retrieve a row with only specific columns
IQSDataTableRow limitedRow = await customersTable.GetRowByIdAsync(
  recordId, batchId, "Name,Email,Phone"
);

if (row != null)
{
  // Access typed fields and child tables
  string customerName = row["Name"].ToString();

  // Modify and track changes to fields
  row["Email"] = "new.email@example.com";
  row["Name"] = "New Name";

  // Save changes for the batch
  await QSAppContext.SaveBatchAsync(batchId);

  // Or save only a single batch without affecting other pending changes
  await QSAppContext.SaveBatchOnlyAsync(batchId);
}