Task.Delay 方法

定義

命名空間:: System.Threading.Tasks

組件:: mscorlib.dll, System.Threading.Tasks.dll

組件:: mscorlib.dll

組件:: System.Threading.Tasks.dll

組件:: netstandard.dll

重要

部分資訊涉及發行前產品，在發行之前可能會有大幅修改。 Microsoft 對此處提供的資訊，不做任何明確或隱含的瑕疵擔保。

建立在時間延遲之後完成的工作。

多載

名稱	Description
Delay(TimeSpan, CancellationToken)	建立可在指定時間間隔之後完成的可取消工作。
Delay(Int32, CancellationToken)	建立可在指定毫秒數之後完成的可取消工作。
Delay(Int32)	建立在指定毫秒數之後完成的工作。
Delay(TimeSpan)	建立在指定時間間隔之後完成的工作。

Delay(TimeSpan, CancellationToken)

建立可在指定時間間隔之後完成的可取消工作。

public:
 static System::Threading::Tasks::Task ^ Delay(TimeSpan delay, System::Threading::CancellationToken cancellationToken);

public static System.Threading.Tasks.Task Delay(TimeSpan delay, System.Threading.CancellationToken cancellationToken);

static member Delay : TimeSpan * System.Threading.CancellationToken -> System.Threading.Tasks.Task

Public Shared Function Delay (delay As TimeSpan, cancellationToken As CancellationToken) As Task

參數

delay: TimeSpan

等待完成返回任務的時間範圍，或 Timeout.InfiniteTimeSpan 無限期等待的時間。

cancellationToken: CancellationToken

一個取消標記，供在等待任務完成時觀察。

傳回

Task

表示時間延遲的工作。

例外狀況

ArgumentOutOfRangeException

delay 代表除 Timeout.InfiniteTimeSpan之外的負時間區間。

-或-

delay該參數TotalMilliseconds的性質在 .NET 6 及以上版本中大於 4294967294，或在所有先前版本中大於 Int32.MaxValue。

OperationCanceledException

工作已取消。此例外會儲存在回傳的任務中。

ObjectDisposedException

所提供的 cancellationToken 已經被處理掉。

TaskCanceledException

工作已取消。

範例

以下範例啟動一項任務，包含對方法的呼叫 Delay(TimeSpan, CancellationToken) ，延遲為 1.5 秒。在延遲間隔經過之前，令牌會取消。範例輸出顯示，因此拋出 a TaskCanceledException ，且任務 Status 屬性設為 Canceled。

using System;
using System.Threading;
using System.Threading.Tasks;

public class Example
{
   public static void Main()
   {
      CancellationTokenSource source = new CancellationTokenSource();

      var t = Task.Run(async delegate
              {
                 await Task.Delay(TimeSpan.FromSeconds(1.5), source.Token);
                 return 42;
              });
      source.Cancel();
      try {
         t.Wait();
      }
      catch (AggregateException ae) {
         foreach (var e in ae.InnerExceptions)
            Console.WriteLine("{0}: {1}", e.GetType().Name, e.Message);
      }
      Console.Write("Task t Status: {0}", t.Status);
      if (t.Status == TaskStatus.RanToCompletion)
         Console.Write(", Result: {0}", t.Result);
      source.Dispose();
   }
}
// The example displays output like the following:
//       TaskCanceledException: A task was canceled.
//       Task t Status: Canceled

open System
open System.Threading
open System.Threading.Tasks

let source = new CancellationTokenSource()

let t =
    Task.Run<int>(fun () ->
        task {

            do! Task.Delay(TimeSpan.FromSeconds(1.5), source.Token)
            return 42
        })

source.Cancel()

try
    t.Wait()

with :? AggregateException as ae ->
    for e in ae.InnerExceptions do
        printfn $"{e.GetType().Name}: {e.Message}"

printf $"Task t Status: {t.Status}"

if t.Status = TaskStatus.RanToCompletion then
    printf $", Result: {t.Result}"

source.Dispose()

// The example displays output like the following:
//       TaskCanceledException: A task was canceled.
//       Task t Status: Canceled

Imports System.Threading
Imports System.Threading.Tasks

Module Example
   Public Sub Main()
      Dim source As New CancellationTokenSource()
      
      Dim t = Task.Run(Async Function()
                                Await Task.Delay(TimeSpan.FromSeconds(1.5),
                                                 source.Token)
                                Return 42
                       End Function)
      source.Cancel()
      Try
         t.Wait()
      Catch ae As AggregateException
         For Each e In ae.InnerExceptions
            Console.WriteLine("{0}: {1}", e.GetType().Name, e.Message)
         Next
      End Try
      Console.Write("Task t Status: {0}", t.Status)
      If t.Status = TaskStatus.RanToCompletion Then
         Console.Write(", Result: {0}", t.Result)
      End If
      source.Dispose()
   End Sub
End Module
' The example displays output like the following:
'       TaskCanceledException: A task was canceled.
'       Task t Status: Canceled

請注意，此範例包含潛在的競爭條件：這取決於在取消令牌時以異步方式執行延遲的工作。雖然呼叫至方法的延遲 Delay(TimeSpan, CancellationToken) 1.5 秒使此假設成立，但仍有可能呼叫 Delay(TimeSpan, CancellationToken) 回傳至該方法，且標記尚未取消。在此情況下，此範例會產生下列輸出：

Task t Status: RanToCompletion, Result: 42

備註

若取消標記在指定時間延遲前被發出訊號，則會產生 TaskCanceledException 例外，任務在該 Canceled 狀態下完成。否則，任務在指定時間延遲過後即在該 RanToCompletion 狀態下完成。

關於使用情境及更多範例，請參閱過載文件 Delay(Int32) 。

這個方法取決於系統時鐘。這表示如果參數 delay 小於系統時鐘的解析度（Windows 系統約為 15 毫秒），時間延遲大致等於系統時鐘的解析度。

Note

所使用的系統時鐘與 GetTickCount 相同，且不受 timeBeginPeriod 與 timeEndPeriod 的變更影響。

適用於

Delay(Int32, CancellationToken)

建立可在指定毫秒數之後完成的可取消工作。

public:
 static System::Threading::Tasks::Task ^ Delay(int millisecondsDelay, System::Threading::CancellationToken cancellationToken);

public static System.Threading.Tasks.Task Delay(int millisecondsDelay, System.Threading.CancellationToken cancellationToken);

static member Delay : int * System.Threading.CancellationToken -> System.Threading.Tasks.Task

Public Shared Function Delay (millisecondsDelay As Integer, cancellationToken As CancellationToken) As Task

參數

millisecondsDelay: Int32

等待的毫秒數，或無限等待的 -1。

cancellationToken: CancellationToken

一個取消標記，供在等待任務完成時觀察。

傳回

Task

表示時間延遲的工作。

例外狀況

ArgumentOutOfRangeException

這個 millisecondsDelay 論點小於負1。

OperationCanceledException

工作已取消。此例外會儲存在回傳的任務中。

ObjectDisposedException

所提供的 cancellationToken 已經被處理掉。

TaskCanceledException

工作已取消。

範例

以下範例啟動一項任務，其中包含以一秒延遲呼叫該 Delay(Int32, CancellationToken) 方法。在延遲間隔經過之前，令牌會取消。範例輸出顯示，因此拋出 a TaskCanceledException ，且任務 Status 屬性設為 Canceled。

using System;
using System.Threading;
using System.Threading.Tasks;

public class Example
{
   public static void Main()
   {
      CancellationTokenSource source = new CancellationTokenSource();

      var t = Task.Run(async delegate
              {
                 await Task.Delay(1000, source.Token);
                 return 42;
              });
      source.Cancel();
      try {
         t.Wait();
      }
      catch (AggregateException ae) {
         foreach (var e in ae.InnerExceptions)
            Console.WriteLine("{0}: {1}", e.GetType().Name, e.Message);
      }
      Console.Write("Task t Status: {0}", t.Status);
      if (t.Status == TaskStatus.RanToCompletion)
         Console.Write(", Result: {0}", t.Result);
      source.Dispose();
   }
}
// The example displays the following output:
//       TaskCanceledException: A task was canceled.
//       Task t Status: Canceled

open System
open System.Threading
open System.Threading.Tasks

let source = new CancellationTokenSource()

let t =
    Task.Run<int>(fun () ->
        task {
            do! Task.Delay(1000, source.Token)
            return 42
        })

source.Cancel()

try
    t.Wait()

with :? AggregateException as ae ->
    for e in ae.InnerExceptions do
        printfn $"{e.GetType().Name}: {e.Message}"

printf $"Task t Status: {t.Status}"

if t.Status = TaskStatus.RanToCompletion then
    printf $", Result: {t.Result}"

source.Dispose()


// The example displays the following output:
//       TaskCanceledException: A task was canceled.
//       Task t Status: Canceled

Imports System.Threading
Imports System.Threading.Tasks

Module Example
   Public Sub Main()
      Dim source As New CancellationTokenSource()
      
      Dim t = Task.Run(Async Function()
                                Await Task.Delay(1000, source.Token)
                                Return 42
                       End Function)
      source.Cancel()
      Try
         t.Wait()
      Catch ae As AggregateException
         For Each e In ae.InnerExceptions
            Console.WriteLine("{0}: {1}", e.GetType().Name, e.Message)
         Next
      End Try
      Console.Write("Task t Status: {0}", t.Status)
      If t.Status = TaskStatus.RanToCompletion Then
         Console.Write(", Result: {0}", t.Result)
      End If
      source.Dispose()
   End Sub
End Module
' The example displays the following output:
'       TaskCanceledException: A task was canceled.
'       Task t Status: Canceled

備註

關於使用情境及更多範例，請參閱過載文件 Delay(Int32) 。

這個方法取決於系統時鐘。這表示如果參數 millisecondsDelay 小於系統時鐘的解析度（Windows 系統約為 15 毫秒），時間延遲大致等於系統時鐘的解析度。

Note

所使用的系統時鐘與 GetTickCount 相同，且不受 timeBeginPeriod 與 timeEndPeriod 的變更影響。

適用於

Delay(Int32)

建立在指定毫秒數之後完成的工作。

public:
 static System::Threading::Tasks::Task ^ Delay(int millisecondsDelay);

public static System.Threading.Tasks.Task Delay(int millisecondsDelay);

static member Delay : int -> System.Threading.Tasks.Task

Public Shared Function Delay (millisecondsDelay As Integer) As Task

參數

millisecondsDelay: Int32

等待的毫秒數，或無限等待的 -1。

傳回

Task

表示時間延遲的工作。

例外狀況

ArgumentOutOfRangeException

這個 millisecondsDelay 論點小於負1。

範例

以下範例展示了該 Delay 方法的簡單使用方式。

using System;
using System.Threading.Tasks;

public class Example
{
   public static void Main()
   {
      var t = Task.Run(async delegate
              {
                 await Task.Delay(1000);
                 return 42;
              });
      t.Wait();
      Console.WriteLine("Task t Status: {0}, Result: {1}",
                        t.Status, t.Result);
   }
}
// The example displays the following output:
//        Task t Status: RanToCompletion, Result: 42

open System.Threading.Tasks

let t =
    Task.Run<int>(fun () ->
        task {
            do! Task.Delay 1000
            return 42
        })

t.Wait()
printfn $"Task t Status: {t.Status}, Result: {t.Result}"

// The example displays the following output:
//        Task t Status: RanToCompletion, Result: 42

Imports System.Threading.Tasks

Module Example
   Public Sub Main()
      Dim t = Task.Run(Async Function()
                                Await Task.Delay(1000)
                                Return 42
                       End Function)
      t.Wait()
      Console.WriteLine("Task t Status: {0}, Result: {1}",
                        t.Status, t.Result)
   End Sub
End Module
' The example displays the following output:
'       Task t Status: RanToCompletion, Result: 42

備註

此 Delay 方法通常用於延遲任務全部或部分的運作，時間間隔為指定時間。最常見的是引進時間延遲：

在工作的開頭，如下列範例所示。

Stopwatch sw = Stopwatch.StartNew();
var delay = Task.Delay(1000).ContinueWith(_ =>
                           { sw.Stop();
                             return sw.ElapsedMilliseconds; } );

Console.WriteLine("Elapsed milliseconds: {0}", delay.Result);
// The example displays output like the following:
//        Elapsed milliseconds: 1013

    let sw = Stopwatch.StartNew()

    let delay =
        Task
            .Delay(1000)
            .ContinueWith(fun _ ->
                sw.Stop()
                sw.ElapsedMilliseconds)

    printfn $"Elapsed milliseconds: {delay.Result}"
// The example displays output like the following:
//        Elapsed milliseconds: 1013

Dim sw As Stopwatch = Stopwatch.StartNew()
Dim delay1 = Task.Delay(1000)
Dim delay2 = delay1.ContinueWith( Function(antecedent)
                        sw.Stop()
                        Return sw.ElapsedMilliseconds
                      End Function)

Console.WriteLine("Elapsed milliseconds: {0}", delay2.Result)
' The example displays output like the following:
'        Elapsed milliseconds: 1013

工作正在執行時。在此情況下，對該 Delay 方法的呼叫會作為任務中的子任務執行，如下範例所示。請注意，由於呼叫該 Delay 方法的任務是非同步執行，父任務必須透過關鍵字 await 等待方法完成。

var delay = Task.Run( async () => { Stopwatch sw = Stopwatch.StartNew();
                                    await Task.Delay(2500);
                                    sw.Stop();
                                    return sw.ElapsedMilliseconds; });

Console.WriteLine("Elapsed milliseconds: {0}", delay.Result);
// The example displays output like the following:
//        Elapsed milliseconds: 2501

    let delay =
        Task.Run<int64>(fun () ->
            task {
                let sw = Stopwatch.StartNew()
                do! Task.Delay 2500
                sw.Stop()
                return sw.ElapsedMilliseconds
            })

    printfn $"Elapsed milliseconds: {delay.Result}"
// The example displays output like the following:
//        Elapsed milliseconds: 2501

Dim delay = Task.Run( Async Function()
                         Dim sw As Stopwatch = Stopwatch.StartNew()
                         Await Task.Delay(2500)
                         sw.Stop()
                         Return sw.ElapsedMilliseconds
                      End Function )

Console.WriteLine("Elapsed milliseconds: {0}", delay.Result)
' The example displays output like the following:
'        Elapsed milliseconds: 2501

在指定的時間延遲後，該任務在該 RanToCompletion 狀態下完成。

這個方法取決於系統時鐘。這表示如果參數 millisecondsDelay 小於系統時鐘的解析度（Windows 系統約為 15 毫秒），時間延遲大致等於系統時鐘的解析度。

Note

所使用的系統時鐘與 GetTickCount 相同，且不受 timeBeginPeriod 與 timeEndPeriod 的變更影響。

適用於

Delay(TimeSpan)

建立在指定時間間隔之後完成的工作。

public:
 static System::Threading::Tasks::Task ^ Delay(TimeSpan delay);

public static System.Threading.Tasks.Task Delay(TimeSpan delay);

static member Delay : TimeSpan -> System.Threading.Tasks.Task

Public Shared Function Delay (delay As TimeSpan) As Task

參數

delay: TimeSpan

等待完成返回任務的時間範圍，或 Timeout.InfiniteTimeSpan 無限期等待的時間。

傳回

Task

表示時間延遲的工作。

例外狀況

ArgumentOutOfRangeException

delay 代表除 Timeout.InfiniteTimeSpan之外的負時間區間。

-或-

delay該參數TotalMilliseconds的性質在 .NET 6 及以上版本中大於 4294967294，或在所有先前版本中大於 Int32.MaxValue。

範例

以下範例展示了該 Delay 方法的簡單使用方式。

using System;
using System.Threading.Tasks;

public class Example
{
   public static void Main()
   {
      var t = Task.Run(async delegate
              {
                 await Task.Delay(TimeSpan.FromSeconds(1.5));
                 return 42;
              });
      t.Wait();
      Console.WriteLine("Task t Status: {0}, Result: {1}",
                        t.Status, t.Result);
   }
}
// The example displays the following output:
//        Task t Status: RanToCompletion, Result: 42

open System
open System.Threading.Tasks

let t =
    Task.Run<int>(fun () ->
        task {
            do! Task.Delay(TimeSpan.FromSeconds 1.5)
            return 42
        })

t.Wait()
printfn $"Task t Status: {t.Status}, Result: {t.Result}"

// The example displays the following output:
//        Task t Status: RanToCompletion, Result: 42

Imports System.Threading.Tasks

Module Example
   Public Sub Main()
      Dim t = Task.Run(Async Function()
                                Await Task.Delay(TimeSpan.FromSeconds(1.5))
                                Return 42
                       End Function)
      t.Wait()
      Console.WriteLine("Task t Status: {0}, Result: {1}",
                        t.Status, t.Result)
   End Sub
End Module
' The example displays the following output:
'       Task t Status: RanToCompletion, Result: 42

備註

在指定的時間延遲後，任務即以狀態完成 RanToCompletion 。

關於使用情境及更多範例，請參閱過載文件 Delay(Int32) 。

這個方法取決於系統時鐘。這表示如果參數 delay 小於系統時鐘的解析度（Windows 系統約為 15 毫秒），時間延遲大致等於系統時鐘的解析度。

Note

所使用的系統時鐘與 GetTickCount 相同，且不受 timeBeginPeriod 與 timeEndPeriod 的變更影響。

適用於

意見反應

此頁面對您有幫助嗎？