IArxBatchScope

Definition

Namespace

ARX.SDK.Services

Package

ARX.SDK

public interface IArxBatchScope : IAsyncDisposable

Properties

• ArxBatchState State { get; }

  The scope's state.

• int BatchCount { get; }

  The number of calls made through the scope, successful or not. Reads count too. Each call's number (1-based) is its batch number.

• long RowsWritten { get; }

  Rows written by successful calls that are still in the transaction; 0 once the scope is rolled back.

• IReadOnlyList<int> FailedBatches { get; }

  The batch numbers of the calls that failed, in order.

Methods

• Task<ArxRecordId> CreateAsync(ArxEntity entity, CancellationToken cancellationToken = default)

  Inserts one entity inside the scope's transaction and returns its id, which is also set on RecordId.

  Parameter	Type	Description
  entity	ArxEntity	The record to create: its table and the attributes to write. Its RecordId is set to the new id.
  cancellationToken	CancellationToken= default	Cancels the call.

• Task<IReadOnlyList<ArxRecordId>> CreateMultipleAsync(IReadOnlyList<ArxEntity> entities, CancellationToken cancellationToken = default)

  Inserts the entities inside the scope's transaction, all or nothing, and returns their ids: one per entity, in list order, the same instances that are set on each entity's RecordId. An empty list returns an empty list.

  Parameter	Type	Description
  entities	IReadOnlyList<ArxEntity>	The records to create, all or nothing; their ids come back in the same order.
  cancellationToken	CancellationToken= default	Cancels the call.

• Task<int> UpdateAsync(ArxEntity entity, ArxUpdateOptions? options = null, CancellationToken cancellationToken = default)

  Updates the rows entity matches inside the scope's transaction and returns how many changed. Nothing matched is ARX2002.

  Parameter	Type	Description
  entity	ArxEntity	The change: its table, the attributes to write (null clears a column; an attribute left out keeps its value), and the id, key or columns that find the row.
  options	ArxUpdateOptions?= null	How the rows are found (Match) and checked; null for the defaults (by id).
  cancellationToken	CancellationToken= default	Cancels the call.

• Task<int> UpdateMultipleAsync(IReadOnlyList<ArxEntity> entities, ArxUpdateOptions? options = null, CancellationToken cancellationToken = default)

  Updates the entities inside the scope's transaction, all or nothing, and returns the rows changed. An entity that matched nothing refuses the whole call (ARX2002). An empty list returns 0.

  Parameter	Type	Description
  entities	IReadOnlyList<ArxEntity>	The changes, all or nothing: each carries the attributes to write and what finds its row.
  options	ArxUpdateOptions?= null	How the rows are found (Match) and checked; null for the defaults (by id).
  cancellationToken	CancellationToken= default	Cancels the call.

• Task<int> UpdateMultipleAsync(ArxEntity values, ArxFilterExpression filter, ArxFilterWriteOptions? options = null, CancellationToken cancellationToken = default)

  The update by a filter inside the scope's transaction: returns how many rows changed.

  Parameter	Type	Description
  values	ArxEntity	The table (EntityName) and the attributes to set: null clears a column.
  filter	ArxFilterExpression	The rows to change: conditions on the table's own columns.
  options	ArxFilterWriteOptions?= null	AllRows for an empty filter; null for the defaults.
  cancellationToken	CancellationToken= default	Cancels the call.

• Task<int> DeleteMultipleAsync(string entityName, ArxFilterExpression filter, ArxFilterWriteOptions? options = null, CancellationToken cancellationToken = default)

  The delete by a filter inside the scope's transaction: returns how many rows went.

  Parameter	Type	Description
  entityName	string	The table to delete from.
  filter	ArxFilterExpression	The rows to delete: conditions on the table's own columns.
  options	ArxFilterWriteOptions?= null	AllRows for an empty filter; null for the defaults.
  cancellationToken	CancellationToken= default	Cancels the call.

• Task<IReadOnlyList<ArxRecordId>> CreateMultipleAsync(IReadOnlyList<ArxEntity> entities, ArxCreateMultipleOptions options, CancellationToken cancellationToken = default)

  CreateMultiple with options inside the scope's transaction.

  Parameter	Type	Description
  entities	IReadOnlyList<ArxEntity>	The records to create, all or nothing.
  options	ArxCreateMultipleOptions	ReturnIds false to skip reading the ids back.
  cancellationToken	CancellationToken= default	Cancels the call.

• Task<bool> DeleteAsync(string entityName, ArxRecordId id, CancellationToken cancellationToken = default)

  Deletes the record with this id inside the scope's transaction; false when there was none. The id converts from a long, int, Guid or string, so DeleteAsync("account", 42L) works as it is.

  Parameter	Type	Description
  entityName	string	The table to delete from.
  id	ArxRecordId	The record's id: the value Create returned, or a plain value of the declared id's type.
  cancellationToken	CancellationToken= default	Cancels the call.

• Task<int> DeleteAsync(ArxEntity entity, ArxDeleteOptions? options = null, CancellationToken cancellationToken = default)

  Deletes the rows entity matches inside the scope's transaction and returns how many went.

  Parameter	Type	Description
  entity	ArxEntity	The record to delete: its table and the id, key or columns that find it.
  options	ArxDeleteOptions?= null	How the rows are found (Match) and checked; null for the defaults (by id).
  cancellationToken	CancellationToken= default	Cancels the call.

• Task<int> DeleteMultipleAsync<TId>(string entityName, IReadOnlyCollection<TId> ids, CancellationToken cancellationToken = default)

  Deletes the records with these ids inside the scope's transaction, all or nothing, and returns how many existed. Duplicates count once. One method for every id type: a list of long, int, Guid, string or ArxRecordId; another element type is ARX1007 UnsupportedValueType.

  Parameter	Type	Description
  entityName	string	The table to delete from.
  ids	IReadOnlyCollection<TId>	The ids of the records to delete; ids that match nothing are left out of the count.
  cancellationToken	CancellationToken= default	Cancels the call.

• Task<int> DeleteMultipleAsync(IReadOnlyList<ArxEntity> entities, ArxDeleteOptions? options = null, CancellationToken cancellationToken = default)

  Deletes the rows the entities match inside the scope's transaction, all or nothing, and returns how many went.

  Parameter	Type	Description
  entities	IReadOnlyList<ArxEntity>	The records to delete, all or nothing, each found by its id or by the match's columns.
  options	ArxDeleteOptions?= null	How the rows are found (Match) and checked; null for the defaults (by id).
  cancellationToken	CancellationToken= default	Cancels the call.

• Task<ArxEntity?> RetrieveAsync(string entityName, ArxRecordId id, ArxColumnSet? columns = null, CancellationToken cancellationToken = default)

  Reads one record by id (the value Create returned, or a long, int, Guid or string) inside the scope's transaction; null when not found. On the SQL providers and MongoDB it sees the scope's own writes; DynamoDB sends writes at commit, so a read before it sees only what is committed.

  Parameter	Type	Description
  entityName	string	The table or view to read.
  id	ArxRecordId	The record's id: the value Create returned, or a plain value of the declared id's type.
  columns	ArxColumnSet?= null	The columns to read; null or an empty set reads every column. The declared id is always read.
  cancellationToken	CancellationToken= default	Cancels the call.

• Task<ArxEntity?> RetrieveAsync(ArxEntity match, ArxRetrieveOptions? options = null, CancellationToken cancellationToken = default)

  Reads the one record the entity matches (an ArxMatch in Match) inside the scope's transaction.

  Parameter	Type	Description
  match	ArxEntity	The record to find: its table, and the values of the id, the declared key or the columns that find it.
  options	ArxRetrieveOptions?= null	How the row is found and read (match, command timeout, lookup names); null for the defaults.
  cancellationToken	CancellationToken= default	Cancels the call.

• Task<ArxEntityCollection> RetrieveMultipleAsync(ArxQueryExpression query, ArxRetrieveOptions? options = null, CancellationToken cancellationToken = default)

  Runs a query inside the scope's transaction. On the SQL providers and MongoDB it sees the scope's own writes; on DynamoDB, only what is committed.

  Parameter	Type	Description
  query	ArxQueryExpression	The query: its row source, columns, criteria, links, order, paging and aggregates.
  options	ArxRetrieveOptions?= null	How the row is found and read (match, command timeout, lookup names); null for the defaults.
  cancellationToken	CancellationToken= default	Cancels the call.

• Task<ArxExecuteResult> ExecuteAsync(ArxProcedureExpression procedure, ArxExecuteOptions? options = null, CancellationToken cancellationToken = default)

  Calls a procedure or function inside the scope's transaction: it sees the scope's writes, and a failed call is undone alone. A procedure that commits or rolls back by itself can't run in a scope (ARX8001).

  Parameter	Type	Description
  procedure	ArxProcedureExpression	The procedure or function to call, with its arguments.
  options	ArxExecuteOptions?= null	Options of the call (paging, command timeout); null for the defaults.
  cancellationToken	CancellationToken= default	Cancels the call.

• Task CommitAsync(CancellationToken cancellationToken = default)

  Commits everything written through the scope. If the database refuses the commit (for example a deferred constraint), the error is thrown and the scope is RolledBack. If the connection fails or times out before the database answers, the scope is OutcomeUnknown and the error, not transient, says the work may or may not be saved. A token cancelled before the commit starts rolls the scope back; the commit itself isn't cancelled, because stopping it half way would leave its outcome unknown.

  Parameter	Type	Description
  cancellationToken	CancellationToken= default	Cancels the call.

• Task RollbackAsync(CancellationToken cancellationToken = default)

  Rolls back everything written through the scope. Does nothing if the scope is already rolled back; fails with ARX1010 if it was committed. The rollback itself isn't cancelled.

  Parameter	Type	Description
  cancellationToken	CancellationToken= default	Cancels the call.

Usage

Used in:

• Create an order and update the stock, all or nothingUpdate
• Replace an order's lines: delete, create, update, all or nothingDelete