IArxDataService

Definition

Namespace

ARX.SDK.Services

Package

ARX.SDK

public interface IArxDataService : IArxBatchDataService

Properties

• IArxProviderCapabilities Capabilities { get; }

  What the provider supports: a call outside it is ARX8001.

Methods

• Task<ArxServerCheck> CheckServerAsync(CancellationToken cancellationToken = default)

  What the connected server allows: its version, the capabilities it removes and why.

  Parameter	Type	Description
  cancellationToken	CancellationToken= default	Cancels the call.

• Task ValidateSchemaAsync(CancellationToken cancellationToken = default)

  Compares every table of the schema catalog with the database, and throws with the differences.

  Parameter	Type	Description
  cancellationToken	CancellationToken= default	Cancels the call.

• Task<ArxTransaction> BeginTransactionAsync(CancellationToken cancellationToken = default)

  Begins a transaction on a connection of its own, the same way on every provider: pass the transaction to the calls, then commit it. Disposing it without committing rolls it back, and closes its connection (await using var transaction = await service.BeginTransactionAsync();).

  Parameter	Type	Description
  cancellationToken	CancellationToken= default	Cancels the call.

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

  Sets values' attributes on every row of its table that filter matches, in one call, and returns how many rows changed. UPDATE … SET … WHERE … on the SQL databases.

  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> UpdateMultipleAsync(ArxEntity values, ArxFilterExpression filter, ArxTransaction transaction, ArxFilterWriteOptions? options = null, CancellationToken cancellationToken = default)

  The update by a filter inside an ARX transaction (see UpdateMultipleAsync).

  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.
  transaction	ArxTransaction	The ARX transaction to run in. ARX doesn't commit or roll it back.
  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)

  Deletes every row of the table that filter matches, in one call, and returns how many went. The filter's rules are UpdateMultiple's: the table's own columns, and an empty filter is ARX1001 unless AllRows is set.

  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<int> DeleteMultipleAsync(string entityName, ArxFilterExpression filter, ArxTransaction transaction, ArxFilterWriteOptions? options = null, CancellationToken cancellationToken = default)

  The delete by a filter inside an ARX transaction (see DeleteMultipleAsync).

  Parameter	Type	Description
  entityName	string	The table to delete from.
  filter	ArxFilterExpression	The rows to delete: conditions on the table's own columns.
  transaction	ArxTransaction	The ARX transaction to run in. ARX doesn't commit or roll it back.
  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)

  Creates the records, all or nothing, as CreateMultipleAsync, with options. With ReturnIds false no id is read back: the provider can take its bulk path, a table without a usable id is created without a catalog, and every id returned is None.

  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<IReadOnlyList<ArxRecordId>> CreateMultipleAsync(IReadOnlyList<ArxEntity> entities, ArxCreateMultipleOptions options, ArxTransaction transaction, CancellationToken cancellationToken = default)

  CreateMultiple with options inside an ARX transaction (see CreateMultipleAsync).

  Parameter	Type	Description
  entities	IReadOnlyList<ArxEntity>	The records to create, all or nothing.
  options	ArxCreateMultipleOptions	ReturnIds false to skip reading the ids back.
  transaction	ArxTransaction	The ARX transaction to run in. ARX doesn't commit or roll it back.
  cancellationToken	CancellationToken= default	Cancels the call.

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

  Creates one record and returns its id (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)

  Creates the records, all or nothing, and returns their ids in the order of the 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 records the entity finds (by its id, or the match of the options) and returns how many: 1 by id or a key; by columns every row that matches unless RequireSingleRow. None 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 every entity's record, all or nothing, and returns how many; one that finds none is ARX2002.

  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<bool> DeleteAsync(string entityName, ArxRecordId id, CancellationToken cancellationToken = default)

  Deletes the record with this id: true when it was there.

  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 records the entity finds and returns how many (0 when none; ARX2002 with RequireSingleRow).

  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(IReadOnlyList<ArxEntity> entities, ArxDeleteOptions? options = null, CancellationToken cancellationToken = default)

  Deletes the records the entities find, all or nothing, and returns how many existed.

  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 columns given (all when null); null when it isn't there.

  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<ArxEntityCollection> RetrieveMultipleAsync(ArxQueryExpression query, ArxRetrieveOptions? options = null, CancellationToken cancellationToken = default)

  Runs a query: its records, page and, when asked, total.

  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 (ARX8001 where StoredProcedures isn't supported).

  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<ArxEntity?> RetrieveAsync(ArxEntity match, ArxRetrieveOptions? options = null, CancellationToken cancellationToken = default)

  Reads the one record the entity finds: by its id, or by the match of the options (a declared key, columns); the columns of the options (all when null); null when none is there. On DynamoDB this is how an item of a single table (or one with a sort key) is read by its whole key.

  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<int> DeleteMultipleAsync<TId>(string entityName, IReadOnlyCollection<TId> ids, CancellationToken cancellationToken = default)

  Deletes the records with these ids, 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<ArxRecordId> CreateAsync(ArxEntity entity, ArxTransaction transaction, CancellationToken cancellationToken = default)

  Creates one record in an ARX transaction (from the provider's connection) and returns its id.

  Parameter	Type	Description
  entity	ArxEntity	The record to create: its table and the attributes to write. Its RecordId is set to the new id.
  transaction	ArxTransaction	The ARX transaction to run in (from the provider's connection type). ARX doesn't commit or roll it back.
  cancellationToken	CancellationToken= default	Cancels the call.

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

  Creates the records in an ARX transaction and returns their ids in the order of the list.

  Parameter	Type	Description
  entities	IReadOnlyList<ArxEntity>	The records to create, all or nothing; their ids come back in the same order.
  transaction	ArxTransaction	The ARX transaction to run in (from the provider's connection type). ARX doesn't commit or roll it back.
  cancellationToken	CancellationToken= default	Cancels the call.

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

  Updates the records the entity finds, in an ARX transaction, and returns how many (as the overload without a transaction); none 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.
  transaction	ArxTransaction	The ARX transaction to run in (from the provider's connection type). ARX doesn't commit or roll it back.
  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, ArxTransaction transaction, ArxUpdateOptions? options = null, CancellationToken cancellationToken = default)

  Updates every entity's record in an ARX transaction and returns how many; one that finds none is ARX2002.

  Parameter	Type	Description
  entities	IReadOnlyList<ArxEntity>	The changes, all or nothing: each carries the attributes to write and what finds its row.
  transaction	ArxTransaction	The ARX transaction to run in (from the provider's connection type). ARX doesn't commit or roll it back.
  options	ArxUpdateOptions?= null	How the rows are found (Match) and checked; null for the defaults (by id).
  cancellationToken	CancellationToken= default	Cancels the call.

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

  Deletes the record with this id in an ARX transaction: true when it was there.

  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.
  transaction	ArxTransaction	The ARX transaction to run in (from the provider's connection type). ARX doesn't commit or roll it back.
  cancellationToken	CancellationToken= default	Cancels the call.

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

  Deletes the records the entity finds in an ARX transaction and returns how many.

  Parameter	Type	Description
  entity	ArxEntity	The record to delete: its table and the id, key or columns that find it.
  transaction	ArxTransaction	The ARX transaction to run in (from the provider's connection type). ARX doesn't commit or roll it back.
  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(IReadOnlyList<ArxEntity> entities, ArxTransaction transaction, ArxDeleteOptions? options = null, CancellationToken cancellationToken = default)

  Deletes the records the entities find in an ARX transaction and returns how many existed.

  Parameter	Type	Description
  entities	IReadOnlyList<ArxEntity>	The records to delete, all or nothing, each found by its id or by the match's columns.
  transaction	ArxTransaction	The ARX transaction to run in (from the provider's connection type). ARX doesn't commit or roll it back.
  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, ArxTransaction transaction, ArxColumnSet? columns = null, CancellationToken cancellationToken = default)

  Reads the record with this id in an ARX transaction, or null. On SQL and MongoDB the read sees the transaction's own writes; DynamoDB sends a transaction's writes at commit, so a read there doesn't see them yet.

  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.
  transaction	ArxTransaction	The ARX transaction to run in (from the provider's connection type). ARX doesn't commit or roll it back.
  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, ArxTransaction transaction, ArxRetrieveOptions? options = null, CancellationToken cancellationToken = default)

  Reads the one record the entity finds (by id, a key or columns) in an ARX transaction, or null.

  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.
  transaction	ArxTransaction	The ARX transaction to run in (from the provider's connection type). ARX doesn't commit or roll it back.
  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, ArxTransaction transaction, ArxRetrieveOptions? options = null, CancellationToken cancellationToken = default)

  Runs the query in an ARX transaction and returns the records it finds.

  Parameter	Type	Description
  query	ArxQueryExpression	The query: its row source, columns, criteria, links, order, paging and aggregates.
  transaction	ArxTransaction	The ARX transaction to run in (from the provider's connection type). ARX doesn't commit or roll it back.
  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, ArxTransaction transaction, ArxExecuteOptions? options = null, CancellationToken cancellationToken = default)

  Calls a procedure or function in an ARX transaction (ARX8001 where StoredProcedures isn't declared).

  Parameter	Type	Description
  procedure	ArxProcedureExpression	The procedure or function to call, with its arguments.
  transaction	ArxTransaction	The ARX transaction to run in (from the provider's connection type). ARX doesn't commit or roll it back.
  options	ArxExecuteOptions?= null	Options of the call (paging, command timeout); null for the defaults.
  cancellationToken	CancellationToken= default	Cancels the call.

Usage

Show($"added Fabrikam Robotics through IArxDataService ({data.Capabilities.ProviderName})");

Set the service up for production, scenario 1

Used in:

• Set the service up for productionCreate
• Log every call through ILoggerCreate