C# Reference ยท Async and Concurrency
Task.Delay() method
Reference for Task.Delay in C#: wait without blocking a thread, cancel a delay, use TimeSpan and TimeProvider, and avoid Thread.Sleep in async code.
Task.Delay returns a task that completes after a given amount of time. Unlike Thread.Sleep, it does not block a thread while it waits: a timer fires and the continuation after your await is scheduled then.
Use it for retry back-off, polling loops, simple timeouts and for simulating slow operations in demos and tests. Do not use it to wait for something that you can await directly.
await Task.Delay(TimeSpan.FromMilliseconds(250)); await Task.Delay(1000, cancellationToken);
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 static Task Delay(int millisecondsDelay); public static Task Delay(int millisecondsDelay, CancellationToken cancellationToken); public static Task Delay(TimeSpan delay); public static Task Delay(TimeSpan delay, CancellationToken cancellationToken); public static Task Delay(TimeSpan delay, TimeProvider timeProvider, CancellationToken cancellationToken);
| Parameter | Description |
|---|---|
millisecondsDelay / delay |
How long to wait. Timeout.Infinite (-1) or Timeout.InfiniteTimeSpan waits until cancelled. |
cancellationToken |
Cancels the wait; the task then ends in the Canceled state. |
timeProvider |
The clock to use (.NET 8+). It lets tests control time. |
Returns: a Task that completes successfully when the delay has elapsed.
Errors: ArgumentOutOfRangeException for values below -1 (or a TimeSpan longer than about 49 days). A cancelled token produces a TaskCanceledException when you await the task, and a token that is already cancelled gives an already canceled task.
Usage notes
- Never
Thread.Sleepin async code. It blocks a thread-pool thread;await Task.Delayfrees it. - Not an exact timer. The delay is a minimum. Timer resolution is typically around 1 to 15 ms, and the continuation also waits for a free thread, so do not use it where precise timing matters.
- Always pass a token in services, so shutdown does not wait for long delays.
- Do not write polling loops on a short delay when an event,
TaskCompletionSourceor channel can signal completion directly. - Racing against a delay (
WhenAny(work, Task.Delay(t))) leaves the delay timer running. Cancel it with a token, or usetask.WaitAsync(timeout)instead. - Periodic work: a
whileloop with a delay drifts, because each iteration adds its own run time.PeriodicTimerticks at fixed intervals. - Tests: accept a
TimeProviderparameter in your own code so tests can advance time with a fake provider instead of really waiting. - Zero delay completes immediately and synchronously; use
Task.Yield()if you want to give other work a chance to run.