Robbiblubber.Util.ConsoleToolkit 1.0.9

robbiblubber.org Console Toolkit Library

The robbiblubber.org Console Toolkit Library provides a progress bar and an animated spinner for console applications. Both support custom colors and status text.

The library targets .NET 8 and .NET 10 and has no external package dependencies. It is intended for interactive terminals that support colors and updating the current line.

The repository can be found at https://bitbucket.org/robbiblubber/robbiblubber.consoletoolkit.net/. API documentation is available from https://robbiblubber.lima-city.org/. For general information see http://robbiblubber.org/.

The robbiblubber.org Console Toolkit Library is provided under the MIT license and may be used without restrictions under the conditions of this license agreement.

Progress Bar

ConsoleProgressBar displays progress within an integer range. The default range is 0 to 100, with a bar of 12 characters, square brackets and a percentage:

using Robbiblubber.Util.ConsoleToolkit;

ConsoleProgressBar bar = new()
{
    BarSize = 30,
    Text = "Processing files..."
};

bar.Show();

for(int i = 1; i <= 100; i++)
{
    await Task.Delay(25);                       // perform one step
    bar.Value = i;                             // updates the display
}

bar.Text = "Done.";
bar.Finish();

Changing Value redraws the bar when the value changes. Values outside the range are clamped to Minimum and Maximum. Changing either bound also redraws the bar. Invalid bounds throw an ArgumentOutOfRangeException without changing the range. Set the bounds in an order that keeps Minimum less than or equal to Maximum; for a range of 200 to 300, set Maximum first. An equal minimum and maximum is displayed as 100%.

Show() and Draw() both draw the current state. Other display properties, such as Text and colors, take effect on the next draw:

bar.Text = "Writing output...";
bar.Draw();

Finish() draws the current state and starts a new line; it does not change Value. Set Value to Maximum first if the final display should show 100%. Clear() removes the current display without starting a new line.

Appearance

BarSize sets the number of fields in the bar, excluding brackets, percentage and text. Negative sizes are rejected; zero hides the fields. The filled and empty fields are spaces by default, so the bar is drawn using background colors. Characters can be used instead:

ConsoleProgressBar bar = new()
{
    BarSize = 24,
    FilledField = '#',
    EmptyField = '-',
    FilledBackgroundColor = Console.BackgroundColor,
    FilledForegroundColor = ConsoleColor.Green,
    EmptyForegroundColor = ConsoleColor.DarkGray,
    OpeningBracket = '<',
    ClosingBracket = '>',
    BracketsColor = ConsoleColor.DarkGray,
    PercentageColor = ConsoleColor.Green,
    StatusColor = ConsoleColor.White,
    Text = "Downloading..."
};

bar.Value = 50;

The display has this form (colors are not shown):

<############------------>  50% Downloading...

• FilledForegroundColor and FilledBackgroundColor control filled fields.
• EmptyForegroundColor and EmptyBackgroundColor control empty fields.
• HasBrackets, OpeningBracket, ClosingBracket and BracketsColor control the brackets.
• ShowPercentage and PercentageColor control the percentage.
• Text and StatusColor control the status text.

The common appearance properties are defined by ConsoleProgressBarBase, which can also serve as a base for custom progress indicators.

Spinner

ConsoleSpinner indicates an operation whose progress is not known. Start() begins the animation on a background task; Interval sets the delay between frames in milliseconds (80 by default).

using Robbiblubber.Util.ConsoleToolkit;

ConsoleSpinner spinner = new()
{
    Frames = ConsoleSpinner.LINE,
    SpinnerForegroundColor = ConsoleColor.Cyan,
    Interval = 100
};

spinner.Start("Loading...");
try
{
    await Task.Delay(1000);                     // perform the operation
    spinner.Text = "Processing...";            // shown on the next frame
    await Task.Delay(1000);
}
finally
{
    await spinner.StopAsync(true);             // wait for stop and clear
}

Console.WriteLine("Done.");

Stop() cancels the animation, waits for it to finish and leaves the last frame visible. Stop(true) also clears the display. Stop("Done.") waits for the animation to finish and draws one more frame with the supplied text; it does not start a new line. StopAsync() provides the same behavior without blocking the caller, including the bool and string overloads. Animation errors are propagated by Stop() and StopAsync(); expected cancellation is handled internally.

Clear() only clears the display and does not stop the animation.

Start(text) sets the status text even when the spinner is already running. Calling Start() without an argument sets Text to NULL. A stopped spinner can be started again.

Frames and colors

The built-in frame sequences are:

Frames can be any non-empty string of single-character frames:

ConsoleSpinner spinner = new()
{
    Frames = ".oOoo",
    Interval = 120,
    SpinnerForegroundColor = ConsoleColor.Yellow,
    SpinnerBackgroundColor = Console.BackgroundColor,
    TextForegroundColor = ConsoleColor.White,
    TextBackgroundColor = Console.BackgroundColor
};

Interval must be positive, and Frames must not be NULL or empty; invalid values are rejected by the setters. The frame sequence can be changed while the spinner is running. Each frame is one C# char; emoji and other characters that require surrogate pairs or combining sequences are not supported as individual frames. Unicode styles also require a suitable terminal font.

Console Output

Both indicators rewrite the current line using a carriage return. Keep the complete display within one terminal line and use status text without line breaks or control characters. Wrapped output is not fully cleared.

Use one indicator at a time and coordinate other console output with it. The spinner serializes its own drawing and lifecycle operations, but neither class coordinates console output with other instances or the application. The progress bar is not thread-safe.

Output length is tracked without reading the console cursor. Clearing assumes that each displayed character occupies one terminal column. Redirected output and log files still receive carriage returns and animation frames; use ordinary log messages in those environments.

The spinner temporarily switches Console.OutputEncoding to UTF-8 for each frame and restores the previous encoding afterward. Both indicators restore console colors in a finally block.