MigsLab SDKARX.SDK documentation
Ctrl K

Getting Started

Quick Start

Create and read your first records with ARX.SDK, using the PostgreSQL provider.

  1. Set up your machine

    Follow PostgreSQL: Get started once: the .NET SDK, a new project, the packages, a database with the sample schema, and the connection string. Every sample on this site starts from that setup.

    ARX works on tables that already exist; it never creates them. The sample schema makes the account table used below. To use a table of your own instead, create it first: Your first table shows the statement for each database.

  2. Create a record

    Declare the table's id column once, create the service, set the entity's attributes, and call CreateAsync. It returns the id of the new record.

    C#
    using ARX.SDK.PostgreSql.Services;
using ARX.SDK.Services;

// The connection string comes from the environment (PostgreSQL: Get started sets it).
string connectionString = Environment.GetEnvironmentVariable("ARX_SAMPLES_POSTGRESQL")
    ?? throw new InvalidOperationException("Set ARX_SAMPLES_POSTGRESQL first.");

// Declare each table's id column once, at startup: ARX doesn't guess it. (Installation shows the two other ways.)
var schema = ArxSchemaCatalog.Create()
    .Table("account", ArxIdColumn.Generated<long>("id"))
    .Build();

var service = new ArxPgDbService(connectionString, schema);

var entity = new ArxEntity("account");
entity["name"] = "Northwind Traders";
entity["account_number"] = "QS-0001";   // unique: change it to run this again
entity["employee_count"] = 240;
// A column you don't set gets the table's default (or NULL); entity["x"] = null writes NULL.

// CreateAsync returns the id of the new record.
ArxRecordId id = await service.CreateAsync(entity);

    Why declare what the database already knows? So that a call never has to ask it: ARX reads nothing about the table during a call, and the same declaration works on databases that keep no such schema (MongoDB, DynamoDB). A service made with only a connection string reads the table instead, before each call, which is slower (Using your own tables). To catch a misspelt table or id column at startup rather than at the first call that needs it, call await service.ValidateSchemaAsync() once: it checks every declared table against the database.

    The full, runnable version, with three more scenarios: Create one record and get its id.

  3. Read it back

    RetrieveAsync takes the table, the id CreateAsync returned, and the columns to read. It returns null when no record has that id, so the code says what happens then. Reading a column the record doesn't have (a misspelt name, or one not asked for) gives null too: the names must match the table's.

    C#
    // RetrieveAsync returns null when no record has the id: say what to do then.
ArxEntity read = await service.RetrieveAsync("account", id, new ArxColumnSet("name", "employee_count"))
    ?? throw new InvalidOperationException("The account record isn't there.");

// With a schema catalog the declared id is always read too, so read.RecordId can update or delete this record later.
Console.WriteLine($"{read["name"]}, {read["employee_count"]} employees, RecordId {read.RecordId}");

// Typed values: GetAttributeValue converts a number when nothing is lost, and is an ARX error (ARX4004) for a value of
// another kind. Ask for a nullable type to tell a NULL column from 0.
string name = read.GetAttributeValue<string>("name")!;
int? employees = read.GetAttributeValue<int?>("employee_count");

    The full sample: Retrieve one record. To read many records with conditions, continue with Retrieve many records with a query.

  4. Explore the operations

    Each operation has its own page of samples, from the basics to complete workflows.

    CreateInsert one record and get its id.CreateMultipleInsert many records in one call, one id each.UpdateChange one record by id, key or columns.UpdateMultipleChange many records in one call, all or nothing.DeleteRemove one record.DeleteMultipleRemove many records by id or by entity.RetrieveRead one record by id or key.RetrieveMultipleQuery with conditions, joins, paging and aggregates.ExecuteCall stored procedures and functions.