Home

Progression

Progression is a library written in C# (.NET 3.5) that lets your application easily calculate and report the progress of a series of tasks.

(courtesy of XKCD)

Here's a very simple example that copies some files. Notice the use of the extension method .WithProgress():

void CopyAllFiles(FileList fileList, Folder dest) {
    // Copy each file, reporting progress along the way:
    foreach (var file in fileList.WithProgress()) {
        // Copy the file:
        CopyFile(file, dest)
    }
}

This will cause progress to be reported once for each file, and once more on completion. If there were 3 files, progress would be reported as 0%, 33%, 66%, 100%.

Progression's power is that it also calculates the progress of sub-tasks into the overall progress. This means that you can easily implement progress calculation in any method, and it will automatically apply to the overall calculation! If the CopyFile method in the previous example reported progress, this would contribute to the overall progress:

void CopyFile(File source, Folder dest) {
    // Copy the file line by line, reporting progress along the way:
    foreach (var line in source.ReadLines().WithProgress()) {
        // Write the line:
        dest.AppendLine(source.Filename, line);
    }
}

If there were 3 files again, each with 10 lines, the overall progress would be reported very smoothly from 0% to 100%! And this functionality didn't even require a full line of code.

Progression covers a wide variety of progress calculations, and has some great features:

• The WithProgress extension method works with any IEnumerable<T> list and is extremely easy to implement
• Many additional methods are included for fine-grained manual control of progress tasks:
  • Progress.BeginTask(...)
  • Progress.NextStep()
  • Progress.EndTask()
• Progress can be calculated in several ways:
  • A fixed number of steps - for example, 10 even steps
  • A proportional list of steps - for example, the first step takes 20%, the second takes 50%, and the third takes 30%
  • An unknown number of steps - for example, while reading a stream, progress gets closer and closer to 100% without going over
  • You can even supply your own calculation by implementing IProgressCalculator -- calculate progress any way you can think of!
• Retrieving the progress to display in your UI is extremely easy, too. Progression features thread-safety, so you can:
  • Poll the progress from a foreground thread
  • Subscribe to thread-safe progress events
  • Use a callback for progress events