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.
var progress = new Progress<int>(percent => Console.WriteLine($"{percent}%")); await ImportAsync(progress);
Try it
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.
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
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. WhenReportreturns, 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 ownIProgress<T>that is synchronous. - Create
Progress<T>on the thread you want callbacks on. The context is captured in the constructor, not whenReportruns. - 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 callprogress?.Report(...). - Pair with cancellation. Methods that take progress usually also take a
CancellationToken. - Testing: use a handwritten synchronous
IProgress<T>in unit tests, notProgress<T>, to avoid timing problems.