ArxEntity

Definition

Namespace

ARX.SDK.Services

Package

ARX.SDK

public class ArxEntity

Constructor

• ArxEntity()

  An entity with no table yet: set EntityName before using it.

• ArxEntity(string entityName)

  An empty record of this table.

  Parameter	Type	Description
  entityName	string	The table, or schema.table.

• ArxEntity(string entityName, ArxAttributeCollection attributes)

  An entity with the given attribute collection: a provider reading rows passes one it built.

  Parameter	Type	Description
  entityName	string	The table, or schema.table.
  attributes	ArxAttributeCollection	The attributes to use as they are (not copied).

• ArxEntity(string entityName, int attributeCapacity)

  An entity with room for attributeCapacity attributes, so a provider that knows how many it reads (a result row) fills it without the dictionary growing.

  Parameter	Type	Description
  entityName	string	The table, or schema.table.
  attributeCapacity	int	How many attributes the entity will hold.

Properties

• ArxRecordId? RecordId { get; set; }

  The record's id, of any declared id type: read it with AsInt64(), AsString(), AsGuid() or Value. Set by Create and by every read that knows the table's id. Create reads the id to write from the attributes, never from this property, so an entity ARX created or read can be created again as a copy. An id your code sets here before a Create is refused (ARX1001) unless the id attribute holds the same id: to give a record its id, set the id attribute (entity["id"] = …).

• ArxIdColumn? IdColumn { get; set; }

  The id column for this entity, when no schema declares its table: a service with no schema catalog, and no schema passed to the call. With a schema, setting it is refused (ARX1001), because a table is declared in one place; to declare a table differently for one call, pass a schema to that call instead. Null (the default) means the schema's declaration is used. NoIdColumn for a table with no id.

• IReadOnlyList<ArxKey>? Keys { get; set; }

  The table's business keys for this entity, when no schema declares its table; with a schema, setting them is refused (ARX1001). Optional: null (the default) means the schema's keys, or none. Keys alone don't declare an id. Create doesn't use them; Update and Delete can find rows by them.

• string EntityName { get; set; }

  The table (or schema.table) the record belongs to.

• ArxAttributeCollection Attributes { get; set; }

  The record's values by column name. Create and Update write exactly these; a read fills them.

• object? this[string attributeName] { get; set; }

  A column's value: null when the record has no such attribute. Setting it adds or replaces the attribute.

Methods

• bool Contains(string attributeName)

  True when the entity has the attribute (names are matched ignoring case).

  Parameter	Type	Description
  attributeName	string	The attribute (column) name, matched ignoring case.

• T? GetAttributeValue<T>(string attributeName)

  The attribute's value as T, or its default when the attribute is missing or null (so GetAttributeValue<int> of a NULL column is 0, and GetAttributeValue<int?> is null: ask for a nullable type to tell NULL from 0. Contains is true for a column that was read as NULL).

  Parameter	Type	Description
  attributeName	string	The attribute (column) name, matched ignoring case.

• ArxEntityReference ToEntityReference(string? primaryColumnName = null)

  A reference to this entity's record, for a lookup on another entity. Its Name is the value of primaryColumnName (a lookup's own name when the column is one), or null when no column is named or the entity doesn't have it.

  Parameter	Type	Description
  primaryColumnName	string?= null	The column whose value names the record (a display name), or null.

Usage

var entity = new ArxEntity("account");

Create one record and get its id, scenario 1

Used in:

• Create one record and get its idCreate
• Create a record that points at another oneCreate
• Catch an error by its codeCreate
• Ids that aren't numbers: text and uuidCreate
• Where to declare: on the entity, or a schema for one call, never bothCreate
• Create without a catalogCreate
• A sign-up form creates an accountCreate
• Every supported .NET type, and what SQL Server storesCreate
• Instants, local times, dates and times of dayCreate
• Picklist values checked against the application's catalogCreate
• Turn ARX error codes into messages for the userCreate
• Values and names that come from users or filesCreate
• Natural ids, uuid ids and a table with a compound keyCreate
• Catch an SQL injection attempt on createCreate
• Register ARX in a DI container and inject itCreate
• Several calls in one ARX transaction: commit or roll backCreate
• Load ids and keys from JSON and validate them at startupCreate
• Write to two databases, each with its own serviceCreate
• A security check around creates: log, block, handle false positivesCreate
• Preload the schema at service setup: keys only, data types, StrictCreate
• Set the service up for productionCreate
• Use columns named outside the name rule, through aliasesCreate
• Log every call through ILoggerCreate
• Remember resolved tables, or preload themCreate
• Create many records in one call and get their idsCreateMultiple
• Create many records without a catalogCreateMultiple
• Create many records without reading their idsCreateMultiple
• Save an account's contacts in one callCreateMultiple
• Import a 20,000-item product feed in one callCreateMultiple
• Import 5,000 contacts in batches, in one transactionCreateMultiple
• An order and its lines: all steps or noneCreateMultiple
• Update one recordUpdate
• Clear a value, keep the othersUpdate
• Catch a record that doesn't existUpdate
• Find rows by id, by key or by columnsUpdate
• Update without a catalogUpdate
• An edit form changes some account detailsUpdate
• Turn update errors into messagesUpdate
• Change prices found by a compound keyUpdate
• Catch an SQL injection attempt on updateUpdate
• Updates in one ARX transaction: commit, roll back, abortUpdate
• Create an order and update the stock, all or nothingUpdate
• A security check around updates: batches, allowed fields, false positivesUpdate
• Update on a preloaded schema: keys only, data types, StrictUpdate
• Update many records in one callUpdateMultiple
• Update many records without a catalogUpdateMultiple
• Update every row a filter matchesUpdateMultiple
• Put accounts on hold (selection set, by key)UpdateMultiple
• Reprice 20,000 products from a feedUpdateMultiple
• Stock counts in batches: one transaction, a failed batch skippedUpdateMultiple
• Delete one recordDelete
• Nothing to delete is not an errorDelete
• Delete by key, by compound key, by columnsDelete
• Delete without a catalogDelete
• Remove a contact by id or by emailDelete
• Undo an import of 5,000 contactsDelete
• A referenced record: ARX3002, then delete in orderDelete
• Soft delete: close and restore an accountDelete
• Catch an SQL injection attempt on deleteDelete
• Replace an order's lines: delete, create, update, all or nothingDelete
• A security check around deletes: probing, blocking, unblocking a false positiveDelete
• Delete on a preloaded schema: keys only, StrictDelete
• Delete many records in one callDeleteMultiple
• Delete many records without a catalogDeleteMultiple
• Delete every row a filter matchesDeleteMultiple
• Remove the contacts a user selectedDeleteMultiple
• Deletes in one ARX transaction: roll back or commitDeleteMultiple
• Retrieve one recordRetrieve
• Choose the columns to readRetrieve
• Find a record by id, key or columnsRetrieve
• Retrieve without a catalogRetrieve
• Every data type, written and read backRetrieve
• Read your own writes in an ARX transactionRetrieve
• Retrieve many records with a queryRetrieveMultiple
• Page through resultsRetrieveMultiple
• Query without a catalogRetrieveMultiple
• A contact search screenRetrieveMultiple
• Accounts and contacts in one queryRetrieveMultiple
• A report: accounts by industryRetrieveMultiple
• Dates and times in conditionsRetrieveMultiple
• Read a viewRetrieveMultiple
• Read a function that returns a tableRetrieveMultiple
• Lookups and display namesRetrieveMultiple
• Catch an SQL injection attempt on a searchRetrieveMultiple
• Read in a batch scopeRetrieveMultiple
• Export a large table in pagesRetrieveMultiple
• A security check around a search endpointRetrieveMultiple
• Filter expressions in depth: nesting, recursion, links, And and OrRetrieveMultiple
• Link entities in depth: chains, branches, criteria per level, recursionRetrieveMultiple
• Paging in depth: the total is opt-in, ask once, load more, Top, seek pagingRetrieveMultiple
• Read other row sources: a view in a schema, a summary view, a table with no idRetrieveMultiple
• Read functions in depth: table rows, one row, scalar values, what functions don't take, proceduresRetrieveMultiple
• Views in depth: computed criteria, links both ways, declared ids and lookups, column boundariesRetrieveMultiple
• Retrieve on a preloaded schema: lookups found, column types, Strict, saved JSONRetrieveMultiple
• Call a stored procedureExecute
• Read OUT and INOUT valuesExecute
• Call a function: a value, rows, an effectExecute
• A procedure that returns tablesExecute
• Place an order through a procedureExecute
• A report with several result setsExecute
• Page through a procedure's result: the procedure pages itself, ARX pages a function, ARX pages a result setExecute
• Business errors raised by a procedureExecute
• A nightly job that commits in batchesExecute
• Catch an SQL injection attempt on ExecuteExecute
• Execute in an ARX transactionExecute
• Execute in a batch scope: a refused call undone aloneExecute
• Export what a procedure returns, page by pageExecute
• A security check around Execute: probing, blocking, unblocking a false positiveExecute
• Execute on a preloaded, Strict schema: routines aren't covered, tables areExecute

Notes