feat: add progress and status payloads with configuration options

Author: WolfBublitz

src/Extensions/ILoggerExtensions.cs

@@ -10,6 +10,8 @@ namespace WB.Logging.LogSinks.Console.Spectre;
 /// </summary>
 public static class ILoggerExtensions
 {
+    private static readonly ProgressConfiguration defaultProgressConfiguration = new();
+    
     // ┌─────────────────────────────────────────────────────────────────────────────┐
     // │ Public Methods                                                              │
     // └─────────────────────────────────────────────────────────────────────────────┘
@@ -74,21 +76,22 @@ public static ILogger HorizontalRule(this ILogger @this, string? title = null)
     }
 
     /// <summary>
-    /// Starts a progress with the specified <paramref name="title"/> and <paramref name="progress"/> function. 
-    /// The progress will be automatically completed when the <paramref name="progress"/> function completes.
+    /// Starts a progress with the <paramref name="progressConfiguration"/> running the specified <paramref name="action"/> function. 
+    /// The progress will be automatically completed when the <paramref name="action"/> function completes.
     /// </summary>
     /// <param name="this">The <see cref="ILogger"/> instance to start the progress on.</param>
-    /// <param name="title">The title of the progress.</param>
-    /// <param name="progress">The function that performs the progress.</param>
+    /// <param name="progressConfiguration">The configuration for the progress. This includes settings such as
+    /// <param name="action">The function that performs the progress.</param>
     /// <returns>A task that represents the asynchronous operation.</returns>
-    public static async Task StartProgressAsync(this ILogger @this, string title, Func<ProgressContext, Task> progress)
+    /// <seealso cref="ProgressConfiguration"/>
+    public static async Task StartProgressAsync(this ILogger @this, ProgressConfiguration progressConfiguration, Func<ProgressContext, Task> action)
     {
         ArgumentNullException.ThrowIfNull(@this);
 
         ProgressPayload progressPayload = new()
         {
-            Title = title,
-            Progress = progress,
+            Configuration = progressConfiguration,
+            Action = action,
         };
 
         await @this.FlushAsync().ConfigureAwait(false);
@@ -97,4 +100,40 @@ public static async Task StartProgressAsync(this ILogger @this, string title, Fu
 
         await progressPayload.Completed.ConfigureAwait(false);
     }
+
+    /// <summary>
+    /// Starts a progress running the specified <paramref name="action"/> function. 
+    /// The progress will be automatically completed when the <paramref name="action"/> function completes.
+    /// </summary>
+    /// <param name="this">The <see cref="ILogger"/> instance to start the progress on.</param>
+    /// <param name="action">The function that performs the progress.</param>
+    /// <returns>A task that represents the asynchronous operation.</returns>
+    public static async Task StartProgressAsync(this ILogger @this, Func<ProgressContext, Task> action)
+        => await StartProgressAsync(@this, defaultProgressConfiguration, action).ConfigureAwait(false);
+
+    public static async Task StartStatusAsync(this ILogger @this, StatusConfiguration statusConfiguration, Func<StatusContext, Task> action)
+    {
+        ArgumentNullException.ThrowIfNull(@this);
+
+        StatusPayload statusPayload = new()
+        {
+            Configuration = statusConfiguration,
+            Action = action,
+        };
+
+        await @this.FlushAsync().ConfigureAwait(false);
+
+        @this.Log(null, statusPayload);
+
+        await statusPayload.Completed.ConfigureAwait(false);
+    }
+
+    public static Task StartStatusAsync(this ILogger @this, string statusMessage, Func<StatusContext, Task> action)
+    {
+        ArgumentNullException.ThrowIfNull(@this);
+
+        StatusConfiguration statusConfiguration = new(statusMessage);
+
+        return StartStatusAsync(@this, statusConfiguration, action);
+    }
 }

src/LogMessageWriters/ProgressConsoleMessageWriter.cs

@@ -29,14 +29,16 @@ internal sealed class ProgressConsoleMessageWriter : IAsyncLogMessageWriter<Prog
     /// <inheritdoc/>
     public async ValueTask WriteAsync(DateTimeOffset timestamp, LogLevel? logLevel, IEnumerable<string> senders, ProgressPayload payload)
     {
+        ProgressConfiguration progressConfiguration = payload.Configuration;
+
 #pragma warning disable CA1031 // Do not catch general exception types
         try
         {
             await Writer.Progress()
-                .AutoClear(payload.AutoClear)
-                .AutoRefresh(payload.AutoRefresh)
-                .HideCompleted(payload.HideCompleted)
-                .StartAsync(payload.Progress).ConfigureAwait(false);
+                .AutoClear(progressConfiguration.AutoClear)
+                .AutoRefresh(progressConfiguration.AutoRefresh)
+                .HideCompleted(progressConfiguration.HideCompleted)
+                .StartAsync(payload.Action).ConfigureAwait(false);
 
             payload.SetCompleted();
         }

src/LogMessageWriters/StatusConsoleMessageWriter.cs

@@ -0,0 +1,50 @@
+using System;
+using System.Collections.Generic;
+using System.Threading.Tasks;
+using Spectre.Console;
+using WB.Logging.LogSinks.Base;
+
+namespace WB.Logging.LogSinks.Console.Spectre;
+
+/// <summary>
+/// A log message writer that uses Spectre.Console's status to 
+/// render status updates in the console.
+/// </summary>
+internal sealed class StatusConsoleMessageWriter : IAsyncLogMessageWriter<StatusPayload, IAnsiConsole>
+{
+    // ┌─────────────────────────────────────────────────────────────────────────────┐
+    // │ Public Properties                                                           │
+    // └─────────────────────────────────────────────────────────────────────────────┘
+
+    /// <inheritdoc/>
+    public IAnsiConsole Writer { get; set; } = AnsiConsole.Console;
+
+    /// <inheritdoc/>
+    public IAsyncLogSink? LogSink { get; set; }
+
+    // ┌─────────────────────────────────────────────────────────────────────────────┐
+    // │ Public Methods                                                              │
+    // └─────────────────────────────────────────────────────────────────────────────┘
+
+    /// <inheritdoc/>
+    public async ValueTask WriteAsync(DateTimeOffset timestamp, LogLevel? logLevel, IEnumerable<string> senders, StatusPayload payload)
+    {
+        StatusConfiguration statusConfiguration = payload.Configuration;
+
+#pragma warning disable CA1031 // Do not catch general exception types
+        try
+        {
+            await Writer.Status()
+                .AutoRefresh(statusConfiguration.AutoRefresh)
+                .Spinner(statusConfiguration.Spinner)
+                .StartAsync(statusConfiguration.StatusMessage, payload.Action).ConfigureAwait(false);
+
+            payload.SetCompleted();
+        }
+        catch (Exception exception)
+        {
+            payload.SetException(exception);
+        }
+#pragma warning restore CA1031 // Do not catch general exception types
+    }
+}

src/Payloads/ProgressPayload.cs

@@ -7,7 +7,7 @@ namespace WB.Logging.LogSinks.Console.Spectre;
 /// <summary>
 /// Represents a payload for logging progress using Spectre.Console's progress bars.
 /// </summary>
-public sealed class ProgressPayload
+internal sealed class ProgressPayload
 {
     // ┌─────────────────────────────────────────────────────────────────────────────┐
     // │ Private Fields                                                              │
@@ -20,29 +20,13 @@ public sealed class ProgressPayload
     // └─────────────────────────────────────────────────────────────────────────────┘
 
     /// <summary>
-    /// Gets or sets the title of the progress. 
+    /// Gets or sets the configuration for the progress. This includes settings such as
+    /// whether the progress should be automatically cleared, refreshed, or hide completed tasks.
     /// </summary>
-    public required string Title { get; init; }
+    /// <seealso cref="ProgressConfiguration"/>
+    public required ProgressConfiguration Configuration { get; init; }
 
-    /// <summary>
-    /// Gets or sets the function that performs the progress.
-    /// </summary>
-    public required Func<ProgressContext, Task> Progress { get; init; }
-
-    /// <summary>
-    /// Gets or sets a value indicating whether the progress should be automatically cleared from the console when completed. Default is <c>true</c>.
-    /// </summary>
-    public bool AutoClear { get; init; } = true;
-
-    /// <summary>
-    /// Gets or sets a value indicating whether the progress should be automatically refreshed in the console. Default is <c>true</c>.
-    /// </summary>
-    public bool AutoRefresh { get; init; } = true;
-
-    /// <summary>
-    /// Gets or sets a value indicating whether to hide completed tasks in the progress. Default is <c>true</c>.
-    /// </summary>
-    public bool HideCompleted { get; init; } = true;
+    public required Func<ProgressContext, Task> Action { get; init; }
 
     /// <summary>
     /// Gets a <see cref="Task"/> that represents the completion of the progress. The 

src/Payloads/StatusPayload.cs

@@ -0,0 +1,56 @@
+using System;
+using System.Threading.Tasks;
+using Spectre.Console;
+
+namespace WB.Logging.LogSinks.Console.Spectre;
+
+/// <summary>
+/// Represents a payload for logging progress using Spectre.Console's progress bars.
+/// </summary>
+internal sealed class StatusPayload
+{
+    // ┌─────────────────────────────────────────────────────────────────────────────┐
+    // │ Private Fields                                                              │
+    // └─────────────────────────────────────────────────────────────────────────────┘
+
+    private readonly TaskCompletionSource taskCompletionSource = new();
+
+    // ┌─────────────────────────────────────────────────────────────────────────────┐
+    // │ Public Properties                                                           │
+    // └─────────────────────────────────────────────────────────────────────────────┘
+
+    public required StatusConfiguration Configuration { get; init; }
+
+    /// <summary>
+    /// Gets or sets the action that performs the status update.
+    /// </summary>
+    public required Func<StatusContext, Task> Action { get; init; }
+
+    /// <summary>
+    /// Gets a <see cref="Task"/> that represents the completion of the status. The 
+    /// <see cref="Task"/> will complete when the status is completed or if an exception 
+    /// occurs during the status update. The <see cref="Task"/> will complete successfully if 
+    /// the status update completes successfully, or with an <see cref="Exception"/> if an <see cref="Exception"/> 
+    /// occurs during the status update.
+    /// </summary>
+    public Task Completed => taskCompletionSource.Task;
+
+    // ┌─────────────────────────────────────────────────────────────────────────────┐
+    // │ Public Methods                                                              │
+    // └─────────────────────────────────────────────────────────────────────────────┘
+
+    /// <summary>
+    /// Sets the status as completed, which will complete the <see cref="Completed"/> 
+    /// task. This method should be called when the status is completed successfully.
+    /// </summary>
+    public void SetCompleted()
+        => taskCompletionSource.TrySetResult();
+
+    /// <summary>
+    /// Sets the status as failed, which will complete the <see cref="Completed"/> 
+    /// task with an exception. This method should be called when an error occurs during the status update.
+    /// </summary>
+    /// <param name="exception">The exception that caused the status update to fail.</param>
+    public void SetException(Exception exception)
+        => taskCompletionSource.TrySetException(exception);
+}

src/ProgressConfiguration.cs

@@ -0,0 +1,6 @@
+namespace WB.Logging.LogSinks.Console.Spectre;
+
+public sealed record ProgressConfiguration(
+    bool AutoClear = true,
+    bool AutoRefresh = true,
+    bool HideCompleted = true);

src/StatusConfiguration.cs

@@ -0,0 +1,10 @@
+using Spectre.Console;
+
+namespace WB.Logging.LogSinks.Console.Spectre;
+
+public sealed record StatusConfiguration(
+    string StatusMessage,
+    bool AutoRefresh = true)
+{
+    public Spinner Spinner { get; init; } = Spinner.Known.Dots;
+}