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 实例的 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)
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,释放其所有非托管资源。

(继承自 Task)
Equals(Object)

确定指定的对象是否等于当前对象。

(继承自 Object)
GetAwaiter()

获取用于等待此 Task<TResult>的等待程序。

GetAwaiter()

获取用于等待此 Task的等待程序。

(继承自 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)

扩展方法

AsyncWait<TException>(Task)

表示可以返回值的异步操作。

AwaitWithTimeout(Task, TimeSpan)

表示可以返回值的异步操作。

ToApm(Task, AsyncCallback, Object)

表示可以返回值的异步操作。

ToApm<TResult>(Task<TResult>, AsyncCallback, Object)

表示可以返回值的异步操作。

ToApmEnd(IAsyncResult)

表示可以返回值的异步操作。

ToApmEnd<TResult>(IAsyncResult)

表示可以返回值的异步操作。

Wait(Task, TimeSpan, Action<Exception,TimeSpan,String>, String)

表示可以返回值的异步操作。

WaitForCompletion(Task)

表示可以返回值的异步操作。

WaitForCompletion<TResult>(Task<TResult>)

表示可以返回值的异步操作。

WaitForCompletionNoSpin(Task)

表示可以返回值的异步操作。

WaitForCompletionNoSpin(Task, TimeSpan)

表示可以返回值的异步操作。

WaitForCompletionNoSpin<TResult>(Task<TResult>)

表示可以返回值的异步操作。

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>的所有成员都是线程安全的,可以同时从多个线程使用。

另请参阅