Save an account's contacts in one call

Runs the sample. Generated for this page; it reads the connection string from the environment.

using ArxSamples.MSSQL;
using ArxSamples.MSSQL.Operations.CreateMultiple.RealCases;

// The connection string comes from the environment, never from the code (see "Configure the connection").
var connectionString = Environment.GetEnvironmentVariable("ARX_SAMPLES_SQLSERVER")
    ?? throw new InvalidOperationException("Set the ARX_SAMPLES_SQLSERVER environment variable to your SQL Server connection string.");

await new RealCase1_AddContactsToAnAccount().RunAsync(new SampleContext(connectionString));

The sample, as it is in the repository.

using ARX.SDK;
using ARX.SDK.Services;
using static ArxSamples.MSSQL.SampleOutput;

namespace ArxSamples.MSSQL.Operations.CreateMultiple.RealCases;

/// <summary>
/// A new customer's contacts, entered on one screen and saved in one call, in two scenarios: three contacts with
/// different attributes, and a second save where one row fails, so none is stored.
/// </summary>
public sealed class RealCase1_AddContactsToAnAccount : ISample
{
    public string Name => "create-multiple-real-1-add-contacts-to-an-account";

    public string Title => "Save an account's contacts in one call";

    public async Task RunAsync(SampleContext dbContext)
    {
        // The customer the contacts belong to.
        var account = new ArxEntity("account");
        account["name"] = "Fabrikam Manufacturing";
        account["industry"] = new ArxSelectionSetValue("Industry", Industry.Manufacturing);
        await dbContext.Service.CreateAsync(account);

        await Scenario1_ThreeContactsInOneCallAsync(dbContext, account);

        await Scenario2_OneEmailTaken_NothingIsStoredAsync(dbContext, account);
    }

    /// <summary>1. Three contacts in one call. Rows don't need the same attributes: ARX groups them by shape.</summary>
    private static async Task Scenario1_ThreeContactsInOneCallAsync(SampleContext dbContext, ArxEntity account)
    {
        Step("1. Three contacts in one CreateMultipleAsync");

        var ana = new ArxEntity("contact");
        ana["account_id"] = new ArxEntityReference("account", account.RecordId);
        ana["first_name"] = "Ana";
        ana["last_name"] = "Silva";
        ana["job_title"] = "Purchasing manager";
        ana["email"] = "[email protected]";
        ana["preferred_channel"] = new ArxSelectionSetValue("ContactChannel", 'E');
        ana["consent_given_at"] = new DateTimeOffset(2026, 11, 2, 9, 30, 0, TimeSpan.FromHours(8));

        var ben = new ArxEntity("contact");
        ben["account_id"] = new ArxEntityReference("account", account.RecordId);
        ben["first_name"] = "Ben";
        ben["last_name"] = "Okafor";
        ben["job_title"] = "Plant director";
        ben["email"] = "[email protected]";
        ben["preferred_channel"] = new ArxSelectionSetValue("ContactChannel", 'P');

        // No email or channel for this one, but a birthday and a note.
        var chen = new ArxEntity("contact");
        chen["account_id"] = new ArxEntityReference("account", account.RecordId);
        chen["first_name"] = "Chen";
        chen["last_name"] = "Wei";
        chen["job_title"] = "Accounts payable";
        chen["birthday"] = new DateOnly(1985, 9, 14);
        chen["notes"] = "Prefers calls before 10am.";

        var ids = await dbContext.Service.CreateMultipleAsync(new List<ArxEntity> { ana, ben, chen });
        Show($"Ana {ids[0]}, Ben {ids[1]}, Chen {ids[2]}");

        /* ===========================================================
         * [DIRECT QUERY CHECK]
         * -----------------------------------------------------------
         * SELECT c.first_name, c.last_name, c.email, c.preferred_channel, c.birthday, c.notes
         * FROM contact c
         * JOIN account a ON a.id = c.account_id
         * WHERE a.name = 'Fabrikam Manufacturing'
         * ORDER BY c.id;
         * -- Expect: 3 rows: Ana (E), Ben (P), Chen (a birthday and a note, no email).
         * ===========================================================
         */
    }

    /// <summary>2. A second save where one email is already taken: the whole call is refused, and no entity gets an id.</summary>
    private static async Task Scenario2_OneEmailTaken_NothingIsStoredAsync(SampleContext dbContext, ArxEntity account)
    {
        Step("2. A second save where one email is already taken: nothing is stored");

        var dana = new ArxEntity("contact");
        dana["account_id"] = new ArxEntityReference("account", account.RecordId);
        dana["first_name"] = "Dana";
        dana["last_name"] = "Ruiz";
        dana["email"] = "[email protected]";

        var anaAgain = new ArxEntity("contact");
        anaAgain["account_id"] = new ArxEntityReference("account", account.RecordId);
        anaAgain["first_name"] = "Ana";
        anaAgain["last_name"] = "Silva";
        anaAgain["email"] = "[email protected]";

        try
        {
            await dbContext.Service.CreateMultipleAsync(new List<ArxEntity> { dana, anaAgain });
        }
        catch (ArxDatabaseException error) when (error.Code == ArxErrorCode.UniqueViolation)
        {
            ShowError(error);
            Show($"Dana has no id ({(dana.RecordId == null ? "RecordId is null" : dana.RecordId)}); contacts on the account: "
                + $"{await dbContext.Direct.CountAsync("contact", "account_id = @p0", account.RecordId!.AsInt64())}");
        }

        /* ===========================================================
         * [DIRECT QUERY CHECK]
         * -----------------------------------------------------------
         * SELECT count(*)
         * FROM contact
         * WHERE email = '[email protected]';
         * -- Expect: 0: the whole call was refused, Dana included.
         * ===========================================================
         */
    }
}

  > 1. Three contacts in one CreateMultipleAsync
      Ana 1, Ben 2, Chen 3
  > 2. A second save where one email is already taken: nothing is stored
      caught ArxDatabaseException: ARX3001 UniqueViolation: CreateMultiple on 'contact' violates unique constraint 'contact_email_key'.
      Dana has no id (RecordId is null); contacts on the account: 3