C# Reference ยท Exceptions and Diagnostics
The AggregateException class
Reference for AggregateException in C#: how Task.Wait, Parallel and Task.WhenAll combine failures, and how to use InnerExceptions, Flatten and Handle.
System.AggregateException bundles several exceptions into one. It appears whenever more than one thing can fail at once: Parallel.For and Parallel.ForEach, PLINQ queries, and blocking on tasks with Task.Wait(), Task.Result or Task.WaitAll(). The individual failures are available through its InnerExceptions collection.
When you await a task instead of blocking, the runtime unwraps the aggregate and throws only the first inner exception. That is convenient, but it also means you lose the others. To see them all, keep the task and read task.Exception.
try { Task.WaitAll(taskA, taskB); } catch (AggregateException ae) { foreach (Exception e in ae.InnerExceptions) { /* inspect */ } }
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 class AggregateException : Exception { public AggregateException(); public AggregateException(string? message); public AggregateException(IEnumerable<Exception> innerExceptions); public AggregateException(params Exception[] innerExceptions); public AggregateException(string? message, IEnumerable<Exception> innerExceptions); public ReadOnlyCollection<Exception> InnerExceptions { get; } public AggregateException Flatten(); public void Handle(Func<Exception, bool> predicate); public override Exception GetBaseException(); }
| Member | Description |
|---|---|
InnerExceptions |
All collected exceptions, in the order they were added. |
InnerException |
Only the first of them (inherited from Exception). |
Flatten() |
Returns a new aggregate with nested aggregates expanded into one level. |
Handle(predicate) |
Calls the predicate for each inner exception. If it returns false for any, throws a new AggregateException containing just those. |
GetBaseException() |
Returns the innermost exception that is not an aggregate. |
Errors: ArgumentNullException if an inner exception is null or the collection is null.
Usage notes
- Order is not guaranteed for tasks that run in parallel. Sort or group the exceptions if the output must be stable.
awaitunwraps;Wait()andResultwrap. Blocking calls always hand you anAggregateException, even for a single failure. This is one reason to preferawait.await Task.WhenAll(...)throws only the first exception. InspectwhenAllTask.Exceptionafter catching to see every failure.- Parallel loops stop early. After one iteration throws,
Parallel.ForEachstops starting new iterations, so you may collect fewer exceptions than there were bad items. - Flatten before you enumerate when tasks can themselves contain tasks, so a nested aggregate does not hide the real exception.
Handleis for filtering. Returntruefor exceptions you have dealt with; anything else is rethrown in a new aggregate.- Unobserved task exceptions (a faulted task nobody awaited) are no longer fatal; they surface through
TaskScheduler.UnobservedTaskExceptionafter garbage collection. - Do not create aggregates by hand unless you collect errors yourself, for example while processing a batch and reporting all failures at the end.