Task<TResult> 類別
定義
重要
部分資訊涉及發行前產品,在發行之前可能會有大幅修改。 Microsoft 對此處提供的資訊,不做任何明確或隱含的瑕疵擔保。
表示可傳回值的非同步作業。
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>物件是工作架構非同步模式的其中一個中央元件,會先在 .NET Framework 4 中引進。 由於 物件所 Task<TResult> 執行的工作通常會以非同步方式線上程集區執行緒上執行,而不是在主要應用程式執行緒上同步執行,因此您可以使用 Status 屬性 IsCanceled 以及 、 IsCompleted 和 IsFaulted 屬性來判斷工作的狀態。 最常見的是,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.StartNew 或 TaskFactory<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.Run 和 Task.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 |
取得導致 AggregateException 不當結束的 Task。 如果 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) |
方法
明確介面實作
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> 都是安全線程,而且可以從多個執行緒同時使用。