Skip to content
Tutorials Center
My learning

Topics

C# Reference ยท Async and Concurrency

IProgress<T> and Progress<T>

Reference for IProgress<T> and Progress<T> in C#: report progress from async methods, how callbacks are scheduled and how to test with a simple implementation.

IProgress<T> is a one-method interface for reporting progress: void Report(T value). An async method takes an IProgress<T> parameter, calls Report as it advances, and the caller decides what to do with the values: update a progress bar, write a log line, collect them in a list.

Progress<T> is the ready-made implementation. It runs your callback on the SynchronizationContext that was current when the Progress<T> was created, which is why it is safe to update a UI from it. Without a context, the callback runs on the thread pool.

C#
var progress = new Progress<int>(percent => Console.WriteLine($"{percent}%"));
await ImportAsync(progress);

Try it

C# Reporting from an async method

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

C# Progress and the thread pool

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

Syntax

C#
public interface IProgress<in T>
{
    void Report(T value);
}

public class Progress<T> : IProgress<T>
{
    public Progress();
    public Progress(Action<T> handler);
    public event EventHandler<T>? ProgressChanged;
    protected virtual void OnReport(T value);
}
Member Description
Report(value) Sends one progress value. It should return quickly.
Progress<T>(handler) Creates an object that calls handler for every report.
ProgressChanged An event raised for every report, in addition to the handler.
T Any type: an int percentage, a record with a message and counts, a tuple.

Returns: nothing. Reporting is one-way.

Errors: Progress<T> throws ArgumentNullException if the handler passed to its constructor is null. An exception in the callback runs on a pool thread or the context, so it is not seen by the reporting code and can crash the process if unhandled.

Usage notes

  • Callbacks are asynchronous. Progress<T> posts each report to its captured context. When Report returns, your handler may not have run yet, and when a method returns, the last reports may still be pending.
  • Order is not guaranteed without a context. On the thread pool two reports can run out of order. If order matters, use a context that preserves it, Channel<T>, or your own IProgress<T> that is synchronous.
  • Create Progress<T> on the thread you want callbacks on. The context is captured in the constructor, not when Report runs.
  • Keep payloads small and immutable, because the value is handed to another thread. A record or a tuple is better than a mutable shared object.
  • Do not report too often. A loop that reports every iteration floods the context. Report when the percentage changes or on a time interval.
  • Make the parameter optional (IProgress<T>? progress = null) and call progress?.Report(...).
  • Pair with cancellation. Methods that take progress usually also take a CancellationToken.
  • Testing: use a handwritten synchronous IProgress<T> in unit tests, not Progress<T>, to avoid timing problems.