共用方式為


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 屬性,以及 IsCanceledIsCompletedIsFaulted 屬性來判斷工作的狀態。 最常見的是,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 主題中的一節。 請注意,市集應用程式會遵循 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

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

(繼承來源 Task)
Factory

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

Id

取得這個 Task 實例的標識碼。

(繼承來源 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)
ConfigureAwait(ConfigureAwaitOptions)

設定用來等候此 Task的 awaiter。

ConfigureAwait(ConfigureAwaitOptions)

設定用來等候此 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()

在目前的 TaskScheduler上同步執行 Task

(繼承來源 Task)
RunSynchronously(TaskScheduler)

在提供的 TaskScheduler 上同步執行 Task

(繼承來源 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)
Wait(TimeSpan, CancellationToken)

等候 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)
WaitAsync(TimeSpan, TimeProvider)

取得 Task<TResult>,此 Task<TResult> 完成或指定的逾時到期時完成。

WaitAsync(TimeSpan, TimeProvider)

取得 Task,此 Task 完成或指定的逾時到期時完成。

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

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

WaitAsync(TimeSpan, TimeProvider, CancellationToken)

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

(繼承來源 Task)

明確介面實作

IAsyncResult.AsyncWaitHandle

取得可用來等候工作完成的 WaitHandle

(繼承來源 Task)
IAsyncResult.CompletedSynchronously

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

(繼承來源 Task)

擴充方法

WaitAsync(Task, TimeSpan, TimeProvider, CancellationToken)

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

WaitAsync<TResult>(Task<TResult>, TimeSpan, TimeProvider, CancellationToken)

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

DispatcherOperationWait(Task)

無限期等候基礎 DispatcherOperation 完成。

DispatcherOperationWait(Task, TimeSpan)

等候基礎 DispatcherOperation 完成指定的時間量。

IsDispatcherOperationTask(Task)

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

AsAsyncAction(Task)

傳回代表已啟動工作的 Windows 運行時間異步動作。

AsAsyncOperation<TResult>(Task<TResult>)

會傳回 Windows 運行時間異步操作,代表傳回結果的已啟動工作。

適用於

執行緒安全性

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

另請參閱