Task.Delay 方法

參考

定義

命名空間:: System.Threading.Tasks

組件:: System.Threading.Tasks.dll

組件:: System.Runtime.dll

組件:: mscorlib.dll

組件:: netstandard.dll

重要

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

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

多載

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

Delay(Int32)

來源:: Task.cs

來源:: Task.cs

來源:: Task.cs

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

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 毫秒。

注意

所使用的系統時鐘是 GetTickCount所使用的相同時鐘，這不會受到 timeBeginPeriod 和 timeEndPeriod所做的變更影響。

適用於

Delay(TimeSpan)

來源:: Task.cs

來源:: Task.cs

來源:: Task.cs

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

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 毫秒。

注意

所使用的系統時鐘是 GetTickCount所使用的相同時鐘，這不會受到 timeBeginPeriod 和 timeEndPeriod所做的變更影響。

適用於

Delay(Int32, CancellationToken)

來源:: Task.cs

來源:: Task.cs

來源:: Task.cs

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

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) 方法的工作，並延遲一秒。在延遲間隔經過之前，令牌會取消。此範例的輸出會顯示擲回 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

備註

如果取消標記在指定的時間延遲之前發出訊號，則 TaskCanceledException 例外狀況結果，且工作會以 Canceled 狀態完成。否則，工作會在經過指定的時間延遲之後，以 RanToCompletion 狀態完成。

如需使用案例和其他範例，請參閱 Delay(Int32) 多載的檔。

注意

所使用的系統時鐘是 GetTickCount所使用的相同時鐘，這不會受到 timeBeginPeriod 和 timeEndPeriod所做的變更影響。

適用於

Delay(TimeSpan, CancellationToken)

來源:: Task.cs

來源:: Task.cs

來源:: Task.cs

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

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

工作已取消。

範例

下列範例會啟動工作，其中包含以 1.5 秒延遲呼叫 Delay(TimeSpan, CancellationToken) 方法。在延遲間隔經過之前，令牌會取消。此範例的輸出會顯示擲回 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

備註

如需使用案例和其他範例，請參閱 Delay(Int32) 多載的檔。

注意

所使用的系統時鐘是 GetTickCount所使用的相同時鐘，這不會受到 timeBeginPeriod 和 timeEndPeriod所做的變更影響。

適用於

Delay(TimeSpan, TimeProvider)

來源:: Task.cs

來源:: Task.cs

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

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

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

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

Public Shared Function Delay (delay As TimeSpan, timeProvider As TimeProvider) As Task

參數

delay: TimeSpan

完成傳回的工作之前要等候的 TimeSpan，或 InfiniteTimeSpan 無限期等候。

timeProvider: TimeProvider

要用來解譯 delay的 TimeProvider。

傳回

Task

表示時間延遲的工作。

例外狀況

ArgumentOutOfRangeException

delay 代表 InfiniteTimeSpan以外的負時間間隔。

-或-

delay的 TotalMilliseconds 屬性大於 4294967294。

ArgumentNullException

timeProvider 自變數 null。

適用於

Delay(TimeSpan, TimeProvider, CancellationToken)

來源:: Task.cs

來源:: Task.cs

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

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

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

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

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

參數

delay: TimeSpan

完成傳回的工作之前要等候的 TimeSpan，或 InfiniteTimeSpan 無限期等候。

timeProvider: TimeProvider

要用來解譯 delay的 TimeProvider。

cancellationToken: CancellationToken

等候工作完成時要觀察的取消標記。

傳回

Task

表示時間延遲的工作。

例外狀況

ArgumentOutOfRangeException

delay 代表 InfiniteTimeSpan以外的負時間間隔。

-或-

delay的 TotalMilliseconds 屬性大於 4294967294。

ArgumentNullException

timeProvider 自變數 null。

OperationCanceledException

取消令牌已取消。此例外狀況會儲存在傳回的工作中。

適用於

共用方式為

Task.Delay 方法

定義

多載

Delay(Int32)

參數

傳回

例外狀況

範例

備註

適用於

Delay(TimeSpan)

參數

傳回

例外狀況

範例

備註

適用於

Delay(Int32, CancellationToken)

參數

傳回

例外狀況

範例

備註

適用於

Delay(TimeSpan, CancellationToken)

參數

傳回

例外狀況

範例

備註

適用於

Delay(TimeSpan, TimeProvider)

參數

傳回

例外狀況

適用於

Delay(TimeSpan, TimeProvider, CancellationToken)

參數

傳回

例外狀況

適用於

其他資源