Task<TResult> 類別

定義

表示可傳回值的非同步作業。

generic <typename TResult>
public ref class Task : System::Threading::Tasks::Task
public class Task<TResult> : System.Threading.Tasks.Task
type Task<'Result> = class
    inherit Task
Public Class Task(Of TResult)
Inherits Task

類型參數

TResult

這個 Task<TResult> 所產生之結果的類型。

繼承
Task<TResult>

備註

類別 Task<TResult> 代表傳回值且通常以非同步方式執行的單一作業。 Task<TResult>物件是工作架構非同步模式的其中一個中央元件,會先在 .NET Framework 4 中引進。 由於 物件所 Task<TResult> 執行的工作通常會以非同步方式線上程集區執行緒上執行,而不是在主要應用程式執行緒上同步執行,因此您可以使用 Status 屬性 IsCanceled 以及 、 IsCompletedIsFaulted 屬性來判斷工作的狀態。 最常見的是,Lambda 運算式是用來指定工作要執行的工作。

Task<TResult> 實例可以透過各種方式建立。 從 .NET Framework 4.5 開始,最常見的方法是呼叫靜態 Task.Run<TResult>(Func<TResult>)Task.Run<TResult>(Func<TResult>, CancellationToken) 方法。 這些方法提供簡單的方法來使用預設值啟動工作,而不需取得其他參數。 下列範例會 Task.Run<TResult>(Func<TResult>) 使用 方法來啟動迴圈的工作,然後顯示迴圈反復專案的數目:

using System;
using System.Threading.Tasks;

public class Example
{
   public static void Main()
   {
      var t = Task<int>.Run( () => {
                                      // Just loop.
                                      int max = 1000000;
                                      int ctr = 0;
                                      for (ctr = 0; ctr <= max; ctr++) {
                                         if (ctr == max / 2 && DateTime.Now.Hour <= 12) {
                                            ctr++;
                                            break;
                                         }
                                      }
                                      return ctr;
                                    } );
      Console.WriteLine("Finished {0:N0} iterations.", t.Result);
   }
}
// The example displays output like the following:
//        Finished 1,000,001 loop iterations.
Imports System.Threading.Tasks

Module Example
   Public Sub Main()
      Dim t As Task(Of Integer) = Task.Run(Function()
                                  Dim max As Integer = 1000000
                                  Dim ctr As Integer
                                  For ctr = 0 to max
                                     If ctr = max \ 2 And Date.Now.Hour <= 12 Then
                                        ctr += 1
                                        Exit For
                                     End If
                                  Next
                                  Return ctr
                               End Function)
      Console.WriteLine("Finished {0:N0} iterations.", t.Result)
   End Sub
End Module
' The example displays the following output:
'       Finished 1,000,001 loop iterations

在 .NET Framework 4 中啟動工作的替代方式和最常見方式,就是呼叫靜態 TaskFactory.StartNewTaskFactory<TResult>.StartNew 方法。 屬性 Task.Factory 會傳 TaskFactory 回 物件,而 Task<TResult>.Factory 屬性會傳 TaskFactory<TResult> 回 物件。 其 StartNew 方法的多載可讓您傳遞引數、定義工作建立選項,以及指定工作排程器。 下列範例會 TaskFactory<TResult>.StartNew(Func<TResult>) 使用 方法來啟動工作。 其功能相當於上一個範例中的程式碼。

using System;
using System.Threading.Tasks;

public class Example
{
   public static void Main()
   {
      var t = Task<int>.Factory.StartNew( () => {
                                      // Just loop.
                                      int max = 1000000;
                                      int ctr = 0;
                                      for (ctr = 0; ctr <= max; ctr++) {
                                         if (ctr == max / 2 && DateTime.Now.Hour <= 12) {
                                            ctr++;
                                            break;
                                         }
                                      }
                                      return ctr;
                               } );
      Console.WriteLine("Finished {0:N0} iterations.", t.Result);
   }
}
// The example displays the following output:
//        Finished 1000001 loop iterations
Imports System.Threading.Tasks

Module Example
   Public Sub Main()
      Dim t = Task(Of Integer).Factory.StartNew(Function()
                                  Dim max As Integer = 1000000
                                  Dim ctr As Integer
                                  For ctr = 0 to max
                                     If ctr = max \ 2 And Date.Now.Hour <= 12 Then
                                       ctr += 1
                                       Exit For
                                     End If
                                  Next
                                  Return ctr
                               End Function)
      Console.WriteLine("Finished {0:N0} iterations.", t.Result)
   End Sub
End Module
' The example displays output like the following:
'       Finished 1,000,001 iterations

如需更完整的範例,請參閱 以工作為基礎的非同步程式設計

類別 Task<TResult> 也提供初始化工作的建構函式,但不會排程工作執行。 基於效能考慮, Task.RunTask.Factory.StartNew 方法是建立和排程計算工作的慣用機制,但針對必須分隔工作建立和排程的情況,可以使用建構函式,然後 Start 可以使用工作的 方法來排程工作,以便稍後執行。

從以 .NET Framework 4.6 為目標的桌面應用程式開始,建立和叫用工作的執行緒文化特性會成為執行緒內容的一部分。 也就是說,不論工作執行所在的執行緒目前文化特性為何,工作目前的文化特性都是呼叫執行緒的文化特性。 針對以 .NET Framework 4.6 之前的 .NET Framework 版本為目標的應用程式,工作的文化特性是工作執行所線上程的文化特性。 如需詳細資訊,請參閱主題中的 CultureInfo 一節。 請注意,Microsoft Store應用程式遵循設定中的Windows 執行階段,並取得預設文化特性。

對於未傳回值的作業,您可以使用 Task 類別。 從 C# 7.0 開始,若是實值型別而非參考型別的輕量型工作,請使用 System.Threading.Tasks.ValueTask<TResult> 結構。

建構函式

Task<TResult>(Func<Object,TResult>, Object)

使用指定的函式和狀態,初始化新的 Task<TResult>

Task<TResult>(Func<Object,TResult>, Object, CancellationToken)

使用指定的動作、狀態和選項,初始化新的 Task<TResult>

Task<TResult>(Func<Object,TResult>, Object, CancellationToken, TaskCreationOptions)

使用指定的動作、狀態和選項,初始化新的 Task<TResult>

Task<TResult>(Func<Object,TResult>, Object, TaskCreationOptions)

使用指定的動作、狀態和選項,初始化新的 Task<TResult>

Task<TResult>(Func<TResult>)

使用指定的函式,初始化新的 Task<TResult>

Task<TResult>(Func<TResult>, CancellationToken)

使用指定的函式,初始化新的 Task<TResult>

Task<TResult>(Func<TResult>, CancellationToken, TaskCreationOptions)

使用指定的函式和建立選項,初始化新的 Task<TResult>

Task<TResult>(Func<TResult>, TaskCreationOptions)

使用指定的函式和建立選項,初始化新的 Task<TResult>

屬性

AsyncState

取得建立 Task 時提供的狀態物件,如果未提供則為 null。

(繼承來源 Task)
CreationOptions

取得用來建立這個工作的 TaskCreationOptions

(繼承來源 Task)
Exception

取得導致 AggregateException 不當結束的 Task。 如果 Task 順利完成,或未擲回任何例外狀況,則這會傳回 null

(繼承來源 Task)
Factory

取得用於建立和設定 Task<TResult> 實例的 Factory 方法。

Id

取得這個 Task 執行個體的 ID。

(繼承來源 Task)
IsCanceled

取得這個 Task 執行個體是否因取消才完成執行。

(繼承來源 Task)
IsCompleted

取得值,這個值表示工作是否已經完成。

(繼承來源 Task)
IsCompletedSuccessfully

取得工作是否執行到完成。

(繼承來源 Task)
IsFaulted

取得 Task 是否因未處理的例外狀況才完成。

(繼承來源 Task)
Result

取得這個 Task<TResult> 的結果值。

Status

取得這個工作的 TaskStatus

(繼承來源 Task)

方法

ConfigureAwait(Boolean)

設定用來等候這個 Task<TResult> 的 awaiter。

ConfigureAwait(Boolean)

設定用來等候這個 Task 的 awaiter。

(繼承來源 Task)
ContinueWith(Action<Task,Object>, Object)

建立當目標 Task 完成時,會接收呼叫端提供的狀態資訊並執行的接續。

(繼承來源 Task)
ContinueWith(Action<Task,Object>, Object, CancellationToken)

建立當目標 Task 完成時,會接收呼叫端提供的狀態資訊和取消語彙基元,並非同步執行的接續。

(繼承來源 Task)
ContinueWith(Action<Task,Object>, Object, CancellationToken, TaskContinuationOptions, TaskScheduler)

建立當目標 Task 完成時,會接收呼叫端提供的狀態資訊和取消語彙基元,並執行的接續。 接續會根據一組指定的條件執行,並使用指定的排程器。

(繼承來源 Task)
ContinueWith(Action<Task,Object>, Object, TaskContinuationOptions)

建立當目標 Task 完成時,會接收呼叫端提供的狀態資訊並執行的接續。 接續會根據一組指定的條件執行。

(繼承來源 Task)
ContinueWith(Action<Task,Object>, Object, TaskScheduler)

建立當目標 Task 完成時,會接收呼叫端提供的狀態資訊並非同步執行的接續。 接續會使用指定的排程器。

(繼承來源 Task)
ContinueWith(Action<Task<TResult>,Object>, Object)

建立當目標 Task<TResult> 完成時,會接收狀態資訊並執行的接續。

ContinueWith(Action<Task<TResult>,Object>, Object, CancellationToken)

建立目標 Task<TResult> 完成時執行的接續工作。

ContinueWith(Action<Task<TResult>,Object>, Object, CancellationToken, TaskContinuationOptions, TaskScheduler)

建立目標 Task<TResult> 完成時執行的接續工作。

ContinueWith(Action<Task<TResult>,Object>, Object, TaskContinuationOptions)

建立目標 Task<TResult> 完成時執行的接續工作。

ContinueWith(Action<Task<TResult>,Object>, Object, TaskScheduler)

建立目標 Task<TResult> 完成時執行的接續工作。

ContinueWith(Action<Task<TResult>>)

建立當目標工作完成時非同步執行的接續。

ContinueWith(Action<Task<TResult>>, CancellationToken)

建立當目標 Task<TResult> 完成時非同步執行的可取消接續。

ContinueWith(Action<Task<TResult>>, CancellationToken, TaskContinuationOptions, TaskScheduler)

建立會根據 continuationOptions 中指定的條件執行的接續。

ContinueWith(Action<Task<TResult>>, TaskContinuationOptions)

建立會根據 continuationOptions 中指定的條件執行的接續。

ContinueWith(Action<Task<TResult>>, TaskScheduler)

建立當目標 Task<TResult> 完成時非同步執行的接續。

ContinueWith(Action<Task>)

建立當目標 Task 完成時非同步執行的接續。

(繼承來源 Task)
ContinueWith(Action<Task>, CancellationToken)

建立當目標 Task 完成時,會接收取消語彙基元並非同步執行的接續。

(繼承來源 Task)
ContinueWith(Action<Task>, CancellationToken, TaskContinuationOptions, TaskScheduler)

建立當目標工作完成時,會根據指定之 TaskContinuationOptions 執行的接續。 接續會接收取消語彙基元,並使用指定的排程器。

(繼承來源 Task)
ContinueWith(Action<Task>, TaskContinuationOptions)

建立當目標工作完成時,會根據指定之 TaskContinuationOptions 執行的接續。

(繼承來源 Task)
ContinueWith(Action<Task>, TaskScheduler)

建立當目標 Task 完成時非同步執行的接續。 接續會使用指定的排程器。

(繼承來源 Task)
ContinueWith<TNewResult>(Func<Task<TResult>,Object,TNewResult>, Object)

建立目標 Task<TResult> 完成時執行的接續工作。

ContinueWith<TNewResult>(Func<Task<TResult>,Object,TNewResult>, Object, CancellationToken)

建立目標 Task<TResult> 完成時執行的接續工作。

ContinueWith<TNewResult>(Func<Task<TResult>,Object,TNewResult>, Object, CancellationToken, TaskContinuationOptions, TaskScheduler)

建立目標 Task<TResult> 完成時執行的接續工作。

ContinueWith<TNewResult>(Func<Task<TResult>,Object,TNewResult>, Object, TaskContinuationOptions)

建立目標 Task<TResult> 完成時執行的接續工作。

ContinueWith<TNewResult>(Func<Task<TResult>,Object,TNewResult>, Object, TaskScheduler)

建立目標 Task<TResult> 完成時執行的接續工作。

ContinueWith<TNewResult>(Func<Task<TResult>,TNewResult>)

建立當目標 Task<TResult> 完成時非同步執行的接續。

ContinueWith<TNewResult>(Func<Task<TResult>,TNewResult>, CancellationToken)

建立當目標 Task<TResult> 完成時非同步執行的接續。

ContinueWith<TNewResult>(Func<Task<TResult>,TNewResult>, CancellationToken, TaskContinuationOptions, TaskScheduler)

建立會根據 continuationOptions 中指定的條件執行的接續。

ContinueWith<TNewResult>(Func<Task<TResult>,TNewResult>, TaskContinuationOptions)

建立會根據 continuationOptions 中指定的條件執行的接續。

ContinueWith<TNewResult>(Func<Task<TResult>,TNewResult>, TaskScheduler)

建立當目標 Task<TResult> 完成時非同步執行的接續。

ContinueWith<TResult>(Func<Task,Object,TResult>, Object)

建立當目標 Task 完成並傳回值時,會接收呼叫端提供的狀態資訊並非同步執行的接續。

(繼承來源 Task)
ContinueWith<TResult>(Func<Task,Object,TResult>, Object, CancellationToken)

建立當目標 Task 完成並傳回值時非同步執行的接續。 接續會接收呼叫端提供的狀態資訊和取消語彙基元。

(繼承來源 Task)
ContinueWith<TResult>(Func<Task,Object,TResult>, Object, CancellationToken, TaskContinuationOptions, TaskScheduler)

建立當目標 Task 完成並傳回值時,會根據指定的工作接續選項來執行的接續。 接續會接收呼叫端提供的狀態資訊和取消語彙基元,並使用指定的排程器。

(繼承來源 Task)
ContinueWith<TResult>(Func<Task,Object,TResult>, Object, TaskContinuationOptions)

建立當目標 Task 完成時,會根據指定的工作接續選項來執行的接續。 接續會接收呼叫端提供的狀態資訊。

(繼承來源 Task)
ContinueWith<TResult>(Func<Task,Object,TResult>, Object, TaskScheduler)

建立當目標 Task 完成時非同步執行的接續。 接續會接收呼叫端提供的狀態資訊,並使用指定的排程器。

(繼承來源 Task)
ContinueWith<TResult>(Func<Task,TResult>)

建立當目標 Task<TResult> 完成並傳回值時非同步執行的接續。

(繼承來源 Task)
ContinueWith<TResult>(Func<Task,TResult>, CancellationToken)

建立當目標 Task 完成並傳回值時非同步執行的接續。 接續會接收取消語彙基元。

(繼承來源 Task)
ContinueWith<TResult>(Func<Task,TResult>, CancellationToken, TaskContinuationOptions, TaskScheduler)

建立會根據指定之接續選項執行並傳回值的接續。 接續會接收取消語彙基元,並使用指定的排程器。

(繼承來源 Task)
ContinueWith<TResult>(Func<Task,TResult>, TaskContinuationOptions)

建立會根據指定之接續選項執行並傳回值的接續。

(繼承來源 Task)
ContinueWith<TResult>(Func<Task,TResult>, TaskScheduler)

建立當目標 Task 完成並傳回值時非同步執行的接續。 接續會使用指定的排程器。

(繼承來源 Task)
Dispose()

釋放 Task 類別目前的執行個體所使用的全部資源。

(繼承來源 Task)
Dispose(Boolean)

處置 Task,並釋放它的所有 Unmanaged 資源。

(繼承來源 Task)
Equals(Object)

判斷指定的物件是否等於目前的物件。

(繼承來源 Object)
GetAwaiter()

取得用來等候這個 Task<TResult> 的 awaiter。

GetAwaiter()

取得用來等候這個 Task 的 awaiter。

(繼承來源 Task)
GetHashCode()

做為預設雜湊函式。

(繼承來源 Object)
GetType()

取得目前執行個體的 Type

(繼承來源 Object)
MemberwiseClone()

建立目前 Object 的淺層複製。

(繼承來源 Object)
RunSynchronously()

在目前的 Task 上同步執行 TaskScheduler

(繼承來源 Task)
RunSynchronously(TaskScheduler)

在提供的 Task 上同步執行 TaskScheduler

(繼承來源 Task)
Start()

啟動 Task,並排定它在目前的 TaskScheduler 執行。

(繼承來源 Task)
Start(TaskScheduler)

啟動 Task,並排定它在指定的 TaskScheduler 執行。

(繼承來源 Task)
ToString()

傳回代表目前物件的字串。

(繼承來源 Object)
Wait()

等候 Task 完成執行。

(繼承來源 Task)
Wait(CancellationToken)

等候 Task 完成執行。 如果在工作完成之前取消語彙基元已取消,則等候會終止。

(繼承來源 Task)
Wait(Int32)

等待 Task 在指定的毫秒數內完成執行。

(繼承來源 Task)
Wait(Int32, CancellationToken)

等候 Task 完成執行。 如果在工作完成之前經過逾時間隔或取消語彙基元已取消,則等候會終止。

(繼承來源 Task)
Wait(TimeSpan)

等待 Task 在指定的時間間隔內完成執行。

(繼承來源 Task)
WaitAsync(CancellationToken)

取得 , Task<TResult> 當這個 Task<TResult> 完成時,或指定的 CancellationToken 已要求取消時,將會完成。

WaitAsync(CancellationToken)

取得 , Task 這個 完成時 Task 或指定的 CancellationToken 已要求取消時完成。

(繼承來源 Task)
WaitAsync(TimeSpan)

取得 , Task<TResult> 當這個 Task<TResult> 完成或指定的逾時到期時,將會完成。

WaitAsync(TimeSpan)

取得 , Task 當這個 Task 完成或指定的逾時到期時,將會完成。

(繼承來源 Task)
WaitAsync(TimeSpan, CancellationToken)

Task<TResult>取得當完成 Task<TResult> 時、指定逾時到期時,或要求指定 CancellationToken 取消時完成的 。

WaitAsync(TimeSpan, CancellationToken)

Task取得當完成 Task 時、指定逾時到期時,或要求指定 CancellationToken 取消時完成的 。

(繼承來源 Task)

明確介面實作

IAsyncResult.AsyncWaitHandle

取得 WaitHandle,這個項目可用來等候工作完成。

(繼承來源 Task)
IAsyncResult.CompletedSynchronously

取得作業是否已同步完成的指示。

(繼承來源 Task)

擴充方法

DispatcherOperationWait(Task)

無限期等候基礎 DispatcherOperation 完成。

DispatcherOperationWait(Task, TimeSpan)

在指定的時間長度中等候,等候基礎 DispatcherOperation 完成。

IsDispatcherOperationTask(Task)

傳回值,表示這個 Task 是否與 DispatcherOperation 關聯。

AsAsyncAction(Task)

傳回代表已開始的動作的 Windows 執行階段非同步動作。

AsAsyncOperation<TResult>(Task<TResult>)

傳回 Windows 執行階段非同步作業,代表會傳回結果的已開始的工作。

適用於

執行緒安全性

除了 以外的 Dispose() 所有成員 Task<TResult> 都是安全線程,而且可以從多個執行緒同時使用。

另請參閱