Progress messages from a procedure

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

using ArxSamples.PostgreSql;
using ArxSamples.PostgreSql.Operations.Execute.RealCases;

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

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

The sample, as it is in the repository.

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

namespace ArxSamples.PostgreSql.Operations.Execute.RealCases;

/// <summary>
/// The messages a routine sends while it runs, in two scenarios: <c>RAISE NOTICE</c> and <c>WARNING</c> come
/// back in <see cref="ArxExecuteResult.Messages"/>, in order, for the application to show or log as it chooses (ARX never
/// writes them to a log); <c>CollectMessages = false</c> leaves them out.
/// </summary>
public sealed class RealCase6_ProgressMessages : ISample
{
    public string Name => "execute-real-6-progress-messages";

    public string Title => "Progress messages from a procedure";

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

        await Scenario2_NotCollectedAsync(dbContext);
    }

    private static ArxProcedureExpression Import(int rows)
    {
        var procedure = new ArxProcedureExpression("sp_import_progress");
        procedure.AddParameter("p_rows", rows);
        return procedure;
    }

    /// <summary>1. An import of 1,000 rows: a notice every 250, then a warning because it's large.</summary>
    private static async Task Scenario1_TheMessagesInOrderAsync(SampleContext dbContext)
    {
        Step("1. The messages, in order");

        var result = await dbContext.Service.ExecuteAsync(Import(1_000));

        foreach (var message in result.Messages)
        {
            Show($"{message.Severity,-7} {message.Text}");
        }

        /* ===========================================================
         * [DIRECT QUERY CHECK]
         * -----------------------------------------------------------
         * SELECT proname, prokind
         * FROM pg_proc
         * WHERE proname = 'sp_import_progress';
         * -- Expect: sp_import_progress, p (the messages themselves are only seen by the session that ran the call).
         * ===========================================================
         */
    }

    /// <summary>2. The same call without collecting them.</summary>
    private static async Task Scenario2_NotCollectedAsync(SampleContext dbContext)
    {
        Step("2. Not collected");

        var result = await dbContext.Service.ExecuteAsync(Import(1_000), new ArxExecuteOptions { CollectMessages = false });
        Show($"{result.Messages.Count} messages");

        /* ===========================================================
         * [DIRECT QUERY CHECK]
         * -----------------------------------------------------------
         * SELECT count(*)
         * FROM pg_proc
         * WHERE proname = 'sp_import_progress' AND prokind = 'p';
         * -- Expect: 1.
         * ===========================================================
         */
    }
}

  > 1. The messages, in order
      NOTICE  imported 250 of 1000 rows
      NOTICE  imported 500 of 1000 rows
      NOTICE  imported 750 of 1000 rows
      NOTICE  imported 1000 of 1000 rows
      WARNING a large import: 1000 rows
  > 2. Not collected
      0 messages