CLI.ProgressBar 1.0.4

CLI.ProgressBar

A simple progress bar for Console applications, cross platform ready, built on top of .NET 8.0 without any external dependency.

Setup

Install CLI.ProgressBar package running the following command line:

dotnet add package CLI.ProgressBar

Usage

In order to use the progress bar include the following namespace:

using CliProgressBar;

Default Progress Bar:

using var progressBar = new ProgressBar();
for (int i = 0; i < 100; i++)
{
	progressBar.AddSteps(1);
	Thread.Sleep(100);
}

Variant Progress Bar:

using var progressBar = new ProgressBar(Layout.Unix);
for (int i = 0; i < 100; i++)
{
	progressBar.AddSteps(1);
	Thread.Sleep(100);
}

Progress Bar with console output:

using var progressBar = new ProgressBar();
for (int i = 0; i < 100; i++)
{
	progressBar.WriteLine($"Line {i + 1}. Console left: {Console.GetCursorPosition().Left}, Console top: {Console.GetCursorPosition().Top}, Buffer Height: {Console.BufferHeight}, Window Height: {Console.WindowHeight}");
	progressBar.Report(i / 100f, $"step {i} of 100");
	Thread.Sleep(100);
}

The progress bar come with more possibilities of customization, check the sample project or the Customization section to see what is possible.

Update progress:

The ProgressBar class provide two way to update is progression:

• By using the AddSteps method, which will increment the progress bar by the given number of steps:

	progressBar.AddSteps(1);

• Or by using the Report method, which will set the progress bar to the given percentage expressed with a float value:

	progressBar.Report(0.5f);

Both methods accepts an optional string parameter used to set a message to display next to the progress bar:

	progressBar.Report(0.5f, "step 50 of 100");
	progressBar.AddSteps(1, "incremented by 1");

Update or define text:

The ProgressBar class provide two methods to update the underlying layout texts:

// Used to configure the main text displayed on the progress bar.
public void SetText(string text)
// Used to configure the additional text displayed on the progress bar, if null is passed the additional text will be hidden.
public void SetAdditionalText(string? text)

Customization

The ProgressBar is highly customizable, you can define the progress bar behaviors and appearance during it's initialization.

ProgressBar:

Layout:

The Layout object is used to configure the aspect of the progress bar. It is composed of 3 elements: a bar, a text and an additional text. The bar is the progression bar, the text is the principal text displayed on the progress bar and the additional text is a secondary optional text displayed on the progress bar.

* Values are required

BarLayout:

The BarLayout object define the appearance of the progression bar.

* Values are required

You can define the desired appearance of the progress bar defining your own Layout like the following:

var bar = new BarLayout(
	new Element<char>('█') { ForegroundColor = ConsoleColor.Green }, 
	new Element<char>('░') { ForegroundColor = ConsoleColor.DarkGreen }
) {
	Direction = BarDirection.Reverse,
	Position = LayoutPosition.Center,
	BracketOptions = BracketLayout.Percentage | BracketLayout.Bar
}

var layout = new Layout(bar, new Element<string>("Principal text"), new Element<string>("Secondary text"));
using var progressBar = new ProgressBar(layout);
// your logic here

Contributing

Any contributions are welcome. 🙌

if you've found a bug, or a possible improvment you would wish to bring to this project, feel free to open an issue or to create a pull request.