Retrieve without a catalog

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

using ArxSamples.MSSQL;
using ArxSamples.MSSQL.Operations.Retrieve.Basics;

// 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 Basic4_WithoutACatalog().RunAsync(new SampleContext(connectionString));

The sample, as it is in the repository.

using ARX.SDK.SQL.Services;
using ARX.SDK.Services;

using static ArxSamples.MSSQL.SampleOutput;

namespace ArxSamples.MSSQL.Operations.Retrieve.Basics;

/// <summary>
/// One record read on a service created with only a connection string, in two scenarios: by the id, which ARX finds
/// from the table's primary key; and by a key, the unique account number.
/// </summary>
/// <remarks>
/// <para>A read by the id reads the table first, which makes it much slower than on a service with a catalog (Create
/// Basic6 says when that is fine). What was read only finds the row: the values come back the same with or without a
/// catalog. So, without one, a read sets no <c>RecordId</c> (ask for the id column, as scenario 2 does) and a lookup
/// column comes back as its plain value, not an <c>ArxEntityReference</c>.</para>
/// </remarks>
public sealed class Basic4_WithoutACatalog : ISample
{
    public string Name => "retrieve-basics-4-without-a-catalog";

    public string Title => "Retrieve without a catalog";

    public async Task RunAsync(SampleContext dbContext)
    {
        var service = new ArxMsSqlDbService(dbContext.ConnectionString);

        var account = new ArxEntity("account");
        account["name"] = "Wingtip Toys";
        account["account_number"] = "ACC-N061";
        account["employee_count"] = 75;
        ArxRecordId id = await service.CreateAsync(account);

        await Scenario1_ByTheIdAsync(service, id);

        await Scenario2_ByAKeyAsync(service);
    }

    /// <summary>1. The table and the id Create returned.</summary>
    private static async Task Scenario1_ByTheIdAsync(ArxMsSqlDbService service, ArxRecordId id)
    {
        Step("1. By the id");

        ArxEntity read = await service.RetrieveAsync("account", id, new ArxColumnSet("name", "employee_count")) ?? throw new InvalidOperationException("The account record isn't there.");

        Show($"{read["name"]}, {read["employee_count"]} employees");

        /* ===========================================================
         * [DIRECT QUERY CHECK]
         * -----------------------------------------------------------
         * SELECT name, employee_count
         * FROM account
         * WHERE account_number = 'ACC-N061';
         * -- Expect: 1 row, Wingtip Toys, 75.
         * ===========================================================
         */
    }

    /// <summary>2. By a key: the entity holds the value, the option names the column; ask for the id to keep it.</summary>
    private static async Task Scenario2_ByAKeyAsync(ArxMsSqlDbService service)
    {
        Step("2. By a key");

        var match = new ArxEntity("account");
        match["account_number"] = "ACC-N061";

        ArxEntity read = await service.RetrieveAsync(match, new ArxRetrieveOptions
        {
            Match = ArxMatch.Key("account_number"),
            Columns = new ArxColumnSet("id", "name")
        }) ?? throw new InvalidOperationException("The record isn't there.");

        Show($"{read["name"]}, id {read["id"]}");

        /* ===========================================================
         * [DIRECT QUERY CHECK]
         * -----------------------------------------------------------
         * SELECT id, name
         * FROM account
         * WHERE account_number = 'ACC-N061';
         * -- Expect: 1 row, Wingtip Toys.
         * ===========================================================
         */
    }
}

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

namespace ArxSamples.MSSQL;

/// <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 SqlClient 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.MSSQL;

/// <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. By the id
      Wingtip Toys, 75 employees
  > 2. By a key
      Wingtip Toys, id 1