Create many records without a catalog

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

using ArxSamples.MySQL;
using ArxSamples.MySQL.Operations.CreateMultiple.Basics;

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

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

The sample, as it is in the repository.

using ARX.SDK.MySQL.Services;
using ARX.SDK.Services;

using static ArxSamples.MySQL.SampleOutput;

namespace ArxSamples.MySQL.Operations.CreateMultiple.Basics;

/// <summary>
/// Many records in one call on a service created with only a connection string: accounts and a country in one list.
/// ARX reads both tables from the database once, before it writes the first row, then returns one id per entity.
/// </summary>
/// <remarks>
/// <para>A call over many rows resolves every table it touches in one go, so the extra round trip is paid once per call,
/// not once per row. It is still slower than a service with a catalog; for imports, declare the catalog or preload it.</para>
/// </remarks>
public sealed class Basic2_WithoutACatalog : ISample
{
    public string Name => "create-multiple-basics-2-without-a-catalog";

    public string Title => "Create many records without a catalog";

    public async Task RunAsync(SampleContext dbContext)
    {
        await Scenario1_TwoTablesInOneCallAsync(dbContext.ConnectionString);
    }

    /// <summary>1. Two tables in one list: each table is read once, then every row is written, all or nothing.</summary>
    private static async Task Scenario1_TwoTablesInOneCallAsync(string connectionString)
    {
        Step("1. Two tables in one call");

        var service = new ArxMySqlDbService(connectionString);

        var first = new ArxEntity("account");
        first["name"] = "Litware Inc.";
        first["account_number"] = "ACC-N011";

        var second = new ArxEntity("account");
        second["name"] = "Proseware Inc.";
        second["account_number"] = "ACC-N012";

        var estonia = new ArxEntity("country");
        estonia["code"] = "EE";
        estonia["name"] = "Estonia";

        // One id per entity, in list order: two generated numbers, then the code that was supplied.
        IReadOnlyList<ArxRecordId> ids = await service.CreateMultipleAsync(new List<ArxEntity> { first, second, estonia });

        Show($"created {string.Join(", ", ids)}");

        /* ===========================================================
         * [DIRECT QUERY CHECK]
         * -----------------------------------------------------------
         * SELECT account_number, name
         * FROM account
         * WHERE account_number IN ('ACC-N011', 'ACC-N012');
         * -- Expect: 2 rows, Litware Inc. and Proseware Inc.
         * SELECT code, name
         * FROM country
         * WHERE code = 'EE';
         * -- Expect: 1 row, Estonia.
         * ===========================================================
         */
    }
}

What every sample is given: the connection string (and the ISample interface the samples implement).

namespace ArxSamples.MySQL;

/// <summary>One documentation sample: a scenario a real application has, shown end to end.</summary>
public interface ISample
{
    /// <summary>The name to run it alone: <c>dotnet run -- &lt;name&gt;</c>.</summary>
    string Name { get; }

    /// <summary>One line on what it shows.</summary>
    string Title { get; }

    Task RunAsync(SampleContext dbContext);
}

/// <summary>
/// What a sample is given. Every sample gets the connection string; the application's service and catalog
/// (SampleContext.Application.cs) and the plain MySqlConnector read-back helper (SampleContext.Direct.cs) live in their own
/// files, so a sample needs only the files it uses.
/// </summary>
public sealed partial class SampleContext
{
    public SampleContext(string connectionString)
    {
        ConnectionString = connectionString;
    }

    public string ConnectionString { get; }
}

How the samples print: Step for each scenario, Show for what it did, ShowError for an error caught on purpose.

using ARX.SDK;

namespace ArxSamples.MySQL;

/// <summary>How the samples print: a numbered step for each scenario, then what it did.</summary>
public static class SampleOutput
{
    /// <summary>The start of a scenario: <c>Step("1. By the id Create returned")</c>.</summary>
    public static void Step(string text) => Console.WriteLine($"  > {text}");

    /// <summary>What the scenario did.</summary>
    public static void Show(string text) => Console.WriteLine($"      {text}");

    /// <summary>An ARX error the scenario caught on purpose.</summary>
    public static void ShowError(ArxException exception)
        => Console.WriteLine($"      caught {exception.GetType().Name}: {exception.Message}");
}

  > 1. Two tables in one call
      created 1, 2, EE