C# Reference ยท Exceptions and Diagnostics
The ExceptionDispatchInfo class
Reference for ExceptionDispatchInfo in C#: capture an exception, rethrow it later or on another thread while keeping the original stack trace intact.
System.Runtime.ExceptionServices.ExceptionDispatchInfo captures an exception together with its stack trace and lets you throw it again later, possibly from a different place or thread, without losing where it first happened. Each rethrow adds to the trace instead of resetting it.
Plain throw; inside a catch block already preserves the trace. ExceptionDispatchInfo is for the cases where you cannot rethrow in the catch: you stored the exception, handed it to another thread, collected it from a task, or you want to run cleanup first and rethrow afterwards. The compiler's await machinery uses it for exactly this reason.
var info = ExceptionDispatchInfo.Capture(exception); // ... later, anywhere: info.Throw();
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 sealed class ExceptionDispatchInfo { public static ExceptionDispatchInfo Capture(Exception source); public static Exception SetCurrentStackTrace(Exception source); public static Exception SetRemoteStackTrace(Exception source, string stackTrace); public static void Throw(Exception source); public Exception SourceException { get; } [DoesNotReturn] public void Throw(); }
| Member | Description |
|---|---|
Capture(source) |
Snapshots the exception and its current stack trace. |
Throw() |
Throws the captured exception again; the old trace is kept and a marker line plus new frames are appended. |
Throw(source) |
Static form: throws source and preserves its existing trace (since .NET 6). |
SourceException |
The exception that was captured. |
SetCurrentStackTrace(source) |
Records the current stack on an exception that was created but not thrown (.NET 5+). |
Errors: ArgumentNullException if source is null.
Usage notes
throw;first. If you are still inside thecatchblock,throw;is simpler and just as good. Never writethrow e;; it resets the stack trace to the current line.- Each
Throw()appends. The textEnd of stack trace from previous locationseparates the original trace from the new part, so you can see both. - Use it when you transfer failures. Examples: a custom scheduler, a producer-consumer pipeline that reports worker errors on the consumer side, or collecting several exceptions and rethrowing the first.
- Rethrowing from
finallyor after cleanup is the other classic use: capture incatch, run cleanup, then callThrow(). awaitdoes this for you. A faulted task stores its exception, andawaitrethrows it throughExceptionDispatchInfo, so the original frames appear in the trace.- Mutating the exception later (for example setting
Data) is allowed; the info holds the same object, not a copy. AggregateExceptionfrom blocking waits wraps the original;awaitunwraps it first. See AggregateException.- Stack trace text is for people. Do not parse it, and do not print line numbers in tests, since they change when the code does.
Related
throw, try, catch, finally, StackTrace, Exception class, Task- Lessons: Exceptions, Async pitfalls