Turn read errors into messages

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

using ArxSamples.MSSQL;
using ArxSamples.MSSQL.Operations.RetrieveMultiple.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 RealCase8_HandleErrors().RunAsync(new SampleContext(connectionString));

The sample, as it is in the repository.

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

namespace ArxSamples.MSSQL.Operations.RetrieveMultiple.RealCases;

/// <summary>
/// Read errors turned into messages, in two scenarios: what the database refuses (a table or column that doesn't
/// exist, a value of the wrong type for its column); and what ARX refuses before the database (an id of the wrong type,
/// an operator without the values it needs, a removed column form).
/// </summary>
public sealed class RealCase8_HandleErrors : ISample
{
    public string Name => "retrieve-multiple-real-8-handle-errors";

    public string Title => "Turn read errors into messages";

    public async Task RunAsync(SampleContext dbContext)
    {
        await Scenario1_WhatTheDatabaseRefusesAsync(dbContext);

        await Scenario2_WhatArxRefusesFirstAsync(dbContext);
    }

    private static string ForTheUser(ArxException error) => error.Code switch
    {
        ArxErrorCode.UndefinedEntity => "That list doesn't exist.",
        ArxErrorCode.UndefinedAttribute => "One of the fields doesn't exist.",
        ArxErrorCode.DataTypeMismatch => "One of the filter values has the wrong type.",
        _ => "The search couldn't be run."
    };

    /// <summary>1. The database refuses: each error has a code to choose the message by.</summary>
    private static async Task Scenario1_WhatTheDatabaseRefusesAsync(SampleContext dbContext)
    {
        Step("1. What the database refuses");

        var noTable = new ArxQueryExpression("accounts_typo");

        var noColumn = new ArxQueryExpression("account");
        noColumn.ColumnSet.AddColumn("fax_number");

        var textForNumber = new ArxQueryExpression("account");
        textForNumber.Criteria.AddCondition("employee_count", ArxConditionOperator.Equal, "forty");

        foreach (var (what, query) in new[] { ("a table that doesn't exist", noTable), ("a column that doesn't exist", noColumn), ("text for a number", textForNumber) })
        {
            try
            {
                await dbContext.Service.RetrieveMultipleAsync(query);
            }
            catch (ArxDatabaseException error)
            {
                Show($"{what}: {error.Code}, the user sees \"{ForTheUser(error)}\"");
            }
        }

        /* ===========================================================
         * [DIRECT QUERY CHECK]
         * -----------------------------------------------------------
         * SELECT CASE WHEN OBJECT_ID('dbo.accounts_typo') IS NULL THEN 1 ELSE 0 END AS no_such_table,
         *        CASE WHEN COL_LENGTH('dbo.account', 'fax_number') IS NULL THEN 1 ELSE 0 END AS no_such_column;
         * -- Expect: 1, 1: nothing was created or changed by the failed reads.
         * ===========================================================
         */
    }

    /// <summary>2. ARX refuses before the database: these never reach it.</summary>
    private static async Task Scenario2_WhatArxRefusesFirstAsync(SampleContext dbContext)
    {
        Step("2. What ARX refuses before the database");

        var between = new ArxQueryExpression("account");
        between.Criteria.AddCondition("employee_count", ArxConditionOperator.Between, 10);

        var removed = new ArxQueryExpression("account");
        removed.ColumnSet.AddColumn("status._opt");

        var attempts = new (string What, Func<Task> Call)[]
        {
            ("a text id for a number id", () => dbContext.Service.RetrieveAsync("account", "ACC-R691")),
            ("Between with one value", () => dbContext.Service.RetrieveMultipleAsync(between)),
            ("a removed column form", () => dbContext.Service.RetrieveMultipleAsync(removed)),
        };

        foreach (var (what, call) in attempts)
        {
            try
            {
                await call();
            }
            catch (ArxException error) when (error is ArxValidationException or ArxNotSupportedException)
            {
                Show($"{what}: {error.Code}");
            }
        }

        /* ===========================================================
         * [DIRECT QUERY CHECK]
         * -----------------------------------------------------------
         * SELECT count(*)
         * FROM account
         * WHERE account_number = 'ACC-R691';
         * -- Expect: 0: the refused reads were about records that don't exist, and changed nothing.
         * ===========================================================
         */
    }
}

  > 1. What the database refuses
      a table that doesn't exist: UndefinedEntity, the user sees "That list doesn't exist."
      a column that doesn't exist: UndefinedAttribute, the user sees "One of the fields doesn't exist."
      text for a number: InvalidValueFormat, the user sees "The search couldn't be run."
  > 2. What ARX refuses before the database
      a text id for a number id: InvalidArgument
      Between with one value: InvalidArgument
      a removed column form: NotSupported