DOCSEARCHbyAlgolia
Submit Docs

ShellProgressBar

repository·master·Indexed 23 days ago

https://github.com/mpdreamz/shellprogressbar

A .NET library for visualizing long-running or concurrent command-line tasks using progress bars in the console. It supports customizable styling via ProgressBarOptions, integration with IProgress<T>, and the ability to spawn descendant progress bars for nested tasks. Includes a FixedDurationBar subclass for tasks with known durations.

Tokens
1.6K
Snippets
6
Records
8
Agent score
31%

What's inside ShellProgressBar

  1. How descendant progressbars work

    master

    A ProgressBar can spawn child progress bars using the Spawn method. This is useful for visualizing concurrent or nested tasks. Each child can have its own ProgressBarOptions.

    By default, child bars collapse when they finish to save space. To keep them visible after completion, set CollapseWhenFinished = false in the child's ProgressBarOptions.

    const int totalTicks = 10;
var options = new ProgressBarOptions
{
	ForegroundColor = ConsoleColor.Yellow,
	BackgroundColor = ConsoleColor.DarkYellow,
	ProgressCharacter = '─'
};
var childOptions = new ProgressBarOptions
{
	ForegroundColor = ConsoleColor.Green,
	BackgroundColor = ConsoleColor.DarkGreen,
	ProgressCharacter = '─'
};
using (var pbar = new ProgressBar(totalTicks, "main progressbar", options))
{
	TickToCompletion(pbar, totalTicks, sleep: 10, childAction: () =>
	{
		using (var child = pbar.Spawn(totalTicks, "child actions", childOptions))
		{
			TickToCompletion(child, totalTicks, sleep: 100);
		}
	});
}

  3. Configure ProgressBarOptions

    master

    Use ProgressBarOptions to customize the appearance and behavior of the progress bar. Key options include:

    • ProgressCharacter: The character used to draw the progress bar.
    • ProgressBarOnBottom: A boolean to flip the position (default is top).
    • ForegroundColor: The color of the progress bar.
    • ForegroundColorDone: The color of the progress bar once completed.
    • BackgroundColor: The color of the inactive portion of the bar.
    • BackgroundCharacter: The character used for the background.
    • DisplayTimeInRealTime: If set to false, the bar only redraws when .Tick() is called, rather than on a 500ms timer.
    • CollapseWhenFinished: Used in child progress bars to determine if they should disappear when done (default is true).

  4. Disable real-time updates

    master

    By default, the progress bar redraws every 500ms. To make the progress bar only update when .Tick() is explicitly called, set DisplayTimeInRealTime = false in ProgressBarOptions.

    const int totalTicks = 5;
var options = new ProgressBarOptions
{
	DisplayTimeInRealTime = false
};
using (var pbar = new ProgressBar(totalTicks, "only draw progress on tick", options))
{
	TickToCompletion(pbar, totalTicks, sleep:1750);
}

  5. Basic usage of ProgressBar

    master

    To create a progress bar, instantiate a ProgressBar with the total number of ticks, a message, and an optional ProgressBarOptions object. Use the Tick() method to advance the progress. You can pass a string to Tick(string message) to update the progress bar's text simultaneously.

    const int totalTicks = 10;
var options = new ProgressBarOptions
{
    ProgressCharacter = '─',
    ProgressBarOnBottom = true
};
using (var pbar = new ProgressBar(totalTicks, "Initial message", options))
{
    pbar.Tick(); //will advance pbar to 1 out of 10.
    //we can also advance and update the progressbar text
    pbar.Tick("Step 2 of 10"); 
}

  6. Customize progress bar styling

    master

    You can style the foreground, background, and completion colors using ConsoleColor via ProgressBarOptions.

    const int totalTicks = 10;
var options = new ProgressBarOptions
{
	ForegroundColor = ConsoleColor.Yellow,
	ForegroundColorDone = ConsoleColor.DarkGreen,
	BackgroundColor = ConsoleColor.DarkGray,
	BackgroundCharacter = '\u2593'
};
using (var pbar = new ProgressBar(totalTicks, "showing off styling", options))
{
	TickToCompletion(pbar, totalTicks, sleep: 500);
}

  7. Use FixedDurationBar for known task durations

    master

    If you know a task will take a specific amount of time, use the FixedDurationBar subclass. It automatically calls Tick() based on real-time progression.

    Note: FixedDurationBar requires real-time updates to function; setting DisplayTimeInRealTime = false will cause an error.

    FixedDurationBar provides:

    • IsCompleted: Indicates if the bar has finished.
    • CompletedHandle: A handle for the completion state.

  8. Report progression using IProgress<T>

    master

    Instead of calling Tick() manually, you can obtain an IProgress<T> instance by calling AsProgress<T>() on your ProgressBar object. This is useful for integrating with standard .NET progress reporting patterns. For example, using AsProgress<float>() allows you to report completion as a percentage between 0.0 and 1.0.

    using ProgressBar progressBar = new ProgressBar(10000, "My Progress Message");
IProgress progress = progressBar.AsProgress<float>();
progress.Report(0.25); // Advances the progress bar to 25%