Task<TResult> Classe

Definição

Namespace:

System.Threading.Tasks

Assembly:

System.Runtime.dll

Origem:

Future.cs

Representa uma operação assíncrona que pode retornar um valor.

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

Parâmetros de tipo

TResult

O tipo do resultado produzido por este Task<TResult>.

Herança

Object

Task

Task<TResult>

Comentários

A classe Task<TResult> representa uma única operação que retorna um valor e que geralmente é executada de forma assíncrona. Task<TResult> objetos são um dos componentes centrais do padrão assíncrono baseado em tarefa introduzido pela primeira vez no .NET Framework 4. Como o trabalho executado por um objeto Task<TResult> normalmente é executado de forma assíncrona em um thread do pool de threads em vez de de forma síncrona no thread principal do aplicativo, você pode usar a propriedade Status, bem como as propriedades IsCanceled, IsCompletede IsFaulted, para determinar o estado de uma tarefa. Mais comumente, uma expressão lambda é usada para especificar o trabalho que a tarefa deve executar.

Task<TResult> instâncias podem ser criadas de várias maneiras. A abordagem mais comum, que está disponível a partir do .NET Framework 4.5, é chamar o método de Task.Run<TResult>(Func<TResult>) estático ou Task.Run<TResult>(Func<TResult>, CancellationToken). Esses métodos fornecem uma maneira simples de iniciar uma tarefa usando valores padrão e sem adquirir parâmetros adicionais. O exemplo a seguir usa o método Task.Run<TResult>(Func<TResult>) para iniciar uma tarefa que faz loops e exibe o número de iterações de loop:

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

Uma alternativa e a maneira mais comum de iniciar uma tarefa no .NET Framework 4 é chamar o método de TaskFactory.StartNew estático ou TaskFactory<TResult>.StartNew. A propriedade Task.Factory retorna um objeto TaskFactory e a propriedade Task<TResult>.Factory retorna um objeto TaskFactory<TResult>. As sobrecargas do método StartNew permitem que você passe argumentos, defina opções de criação de tarefas e especifique um agendador de tarefas. O exemplo a seguir usa o método TaskFactory<TResult>.StartNew(Func<TResult>) para iniciar uma tarefa. Ele é funcionalmente equivalente ao código no exemplo anterior.

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

Para obter exemplos mais completos, consulte de programação assíncrona baseada em tarefa.

A classe Task<TResult> também fornece construtores que inicializam a tarefa, mas que não a agendam para execução. Por motivos de desempenho, os métodos Task.Run e Task.Factory.StartNew são os mecanismos preferenciais para criar e agendar tarefas computacionais, mas para cenários em que a criação e o agendamento de tarefas devem ser separados, os construtores podem ser usados e o método Start da tarefa pode ser usado para agendar a tarefa para execução posteriormente.

Começando com aplicativos da área de trabalho direcionados ao .NET Framework 4.6, a cultura do thread que cria e invoca uma tarefa torna-se parte do contexto do thread. Ou seja, independentemente da cultura atual do thread no qual a tarefa é executada, a cultura atual da tarefa é a cultura do thread de chamada. Para aplicativos destinados a versões do .NET Framework antes do .NET Framework 4.6, a cultura da tarefa é a cultura do thread no qual a tarefa é executada. Para obter mais informações, consulte a seção "Cultura e operações assíncronas baseadas em tarefas" no tópico CultureInfo. Observe que os aplicativos da Loja seguem o Windows Runtime na configuração e obtendo a cultura padrão.

Para operações que não retornam um valor, use a classe Task. A partir do C# 7.0, para uma tarefa mais leve que seja um tipo de valor em vez de um tipo de referência, use a estrutura System.Threading.Tasks.ValueTask<TResult>.

Construtores

Task<TResult>(Func<Object,TResult>, Object)	Inicializa um novo Task<TResult> com a função e o estado especificados.
Task<TResult>(Func<Object,TResult>, Object, CancellationToken)	Inicializa um novo Task<TResult> com a ação, o estado e as opções especificados.
Task<TResult>(Func<Object,TResult>, Object, CancellationToken, TaskCreationOptions)	Inicializa um novo Task<TResult> com a ação, o estado e as opções especificados.
Task<TResult>(Func<Object,TResult>, Object, TaskCreationOptions)	Inicializa um novo Task<TResult> com a ação, o estado e as opções especificados.
Task<TResult>(Func<TResult>)	Inicializa um novo Task<TResult> com a função especificada.
Task<TResult>(Func<TResult>, CancellationToken)	Inicializa um novo Task<TResult> com a função especificada.
Task<TResult>(Func<TResult>, CancellationToken, TaskCreationOptions)	Inicializa um novo Task<TResult> com as opções de função e criação especificadas.
Task<TResult>(Func<TResult>, TaskCreationOptions)	Inicializa um novo Task<TResult> com as opções de função e criação especificadas.

Propriedades

AsyncState	Obtém o objeto de estado fornecido quando o Task foi criado ou nulo se nenhum foi fornecido. (Herdado de Task)
CreationOptions	Obtém o TaskCreationOptions usado para criar essa tarefa. (Herdado de Task)
Exception	Obtém o AggregateException que fez com que o Task acabasse prematuramente. Se o Task concluído com êxito ou ainda não tiver gerado exceções, isso retornará null. (Herdado de Task)
Factory	Obtém um método de fábrica para criar e configurar instâncias de Task<TResult>.
Id	Obtém uma ID para esta instância de Task. (Herdado de Task)
IsCanceled	Obtém se essa Task instância concluiu a execução devido ao cancelamento. (Herdado de Task)
IsCompleted	Obtém um valor que indica se a tarefa foi concluída. (Herdado de Task)
IsCompletedSuccessfully	Obtém se a tarefa foi executada até a conclusão. (Herdado de Task)
IsFaulted	Obtém se o Task concluído devido a uma exceção sem tratamento. (Herdado de Task)
Result	Obtém o valor do resultado deste Task<TResult>.
Status	Obtém o TaskStatus desta tarefa. (Herdado de Task)

Métodos

ConfigureAwait(Boolean)	Configura um aguardador usado para aguardar esta Task<TResult>.
ConfigureAwait(ConfigureAwaitOptions)	Configura um aguardador usado para aguardar esta Task.
ContinueWith(Action<Task,Object>, Object)	Cria uma continuação que recebe informações de estado fornecidas pelo chamador e é executada quando o Task de destino é concluído. (Herdado de Task)
ContinueWith(Action<Task,Object>, Object, CancellationToken)	Cria uma continuação que recebe informações de estado fornecidas pelo chamador e um token de cancelamento e que é executado de forma assíncrona quando o Task de destino é concluído. (Herdado de Task)
ContinueWith(Action<Task,Object>, Object, CancellationToken, TaskContinuationOptions, TaskScheduler)	Cria uma continuação que recebe informações de estado fornecidas pelo chamador e um token de cancelamento e que é executado quando o Task de destino é concluído. A continuação é executada com base em um conjunto de condições especificadas e usa um agendador especificado. (Herdado de Task)
ContinueWith(Action<Task,Object>, Object, TaskContinuationOptions)	Cria uma continuação que recebe informações de estado fornecidas pelo chamador e é executada quando o Task de destino é concluído. A continuação é executada com base em um conjunto de condições especificadas. (Herdado de Task)
ContinueWith(Action<Task,Object>, Object, TaskScheduler)	Cria uma continuação que recebe informações de estado fornecidas pelo chamador e é executada de forma assíncrona quando o Task de destino é concluído. A continuação usa um agendador especificado. (Herdado de Task)
ContinueWith(Action<Task<TResult>,Object>, Object)	Cria uma continuação que é passada informações de estado e que é executada quando o destino Task<TResult> é concluído.
ContinueWith(Action<Task<TResult>,Object>, Object, CancellationToken)	Cria uma continuação que é executada quando o Task<TResult> de destino é concluído.
ContinueWith(Action<Task<TResult>,Object>, Object, CancellationToken, TaskContinuationOptions, TaskScheduler)	Cria uma continuação que é executada quando o Task<TResult> de destino é concluído.
ContinueWith(Action<Task<TResult>,Object>, Object, TaskContinuationOptions)	Cria uma continuação que é executada quando o Task<TResult> de destino é concluído.
ContinueWith(Action<Task<TResult>,Object>, Object, TaskScheduler)	Cria uma continuação que é executada quando o Task<TResult> de destino é concluído.
ContinueWith(Action<Task<TResult>>)	Cria uma continuação que é executada de forma assíncrona quando a tarefa de destino é concluída.
ContinueWith(Action<Task<TResult>>, CancellationToken)	Cria uma continuação cancelável que é executada de forma assíncrona quando o Task<TResult> de destino é concluído.
ContinueWith(Action<Task<TResult>>, CancellationToken, TaskContinuationOptions, TaskScheduler)	Cria uma continuação que é executada de acordo com a condição especificada em continuationOptions.
ContinueWith(Action<Task<TResult>>, TaskContinuationOptions)	Cria uma continuação que é executada de acordo com a condição especificada em continuationOptions.
ContinueWith(Action<Task<TResult>>, TaskScheduler)	Cria uma continuação que é executada de forma assíncrona quando o Task<TResult> de destino é concluído.
ContinueWith(Action<Task>)	Cria uma continuação que é executada de forma assíncrona quando o Task de destino é concluído. (Herdado de Task)
ContinueWith(Action<Task>, CancellationToken)	Cria uma continuação que recebe um token de cancelamento e é executada de forma assíncrona quando o Task de destino é concluído. (Herdado de Task)
ContinueWith(Action<Task>, CancellationToken, TaskContinuationOptions, TaskScheduler)	Cria uma continuação que é executada quando a tarefa de destino compete de acordo com o TaskContinuationOptionsespecificado. A continuação recebe um token de cancelamento e usa um agendador especificado. (Herdado de Task)
ContinueWith(Action<Task>, TaskContinuationOptions)	Cria uma continuação que é executada quando a tarefa de destino é concluída de acordo com o TaskContinuationOptionsespecificado. (Herdado de Task)
ContinueWith(Action<Task>, TaskScheduler)	Cria uma continuação que é executada de forma assíncrona quando o Task de destino é concluído. A continuação usa um agendador especificado. (Herdado de Task)
ContinueWith<TNewResult>(Func<Task<TResult>,Object,TNewResult>, Object)	Cria uma continuação que é executada quando o Task<TResult> de destino é concluído.
ContinueWith<TNewResult>(Func<Task<TResult>,Object,TNewResult>, Object, CancellationToken)	Cria uma continuação que é executada quando o Task<TResult> de destino é concluído.
ContinueWith<TNewResult>(Func<Task<TResult>,Object,TNewResult>, Object, CancellationToken, TaskContinuationOptions, TaskScheduler)	Cria uma continuação que é executada quando o Task<TResult> de destino é concluído.
ContinueWith<TNewResult>(Func<Task<TResult>,Object,TNewResult>, Object, TaskContinuationOptions)	Cria uma continuação que é executada quando o Task<TResult> de destino é concluído.
ContinueWith<TNewResult>(Func<Task<TResult>,Object,TNewResult>, Object, TaskScheduler)	Cria uma continuação que é executada quando o Task<TResult> de destino é concluído.
ContinueWith<TNewResult>(Func<Task<TResult>,TNewResult>)	Cria uma continuação que é executada de forma assíncrona quando o Task<TResult> de destino é concluído.
ContinueWith<TNewResult>(Func<Task<TResult>,TNewResult>, CancellationToken)	Cria uma continuação que é executada de forma assíncrona quando o Task<TResult> de destino é concluído.
ContinueWith<TNewResult>(Func<Task<TResult>,TNewResult>, CancellationToken, TaskContinuationOptions, TaskScheduler)	Cria uma continuação que é executada de acordo com a condição especificada em continuationOptions.
ContinueWith<TNewResult>(Func<Task<TResult>,TNewResult>, TaskContinuationOptions)	Cria uma continuação que é executada de acordo com a condição especificada em continuationOptions.
ContinueWith<TNewResult>(Func<Task<TResult>,TNewResult>, TaskScheduler)	Cria uma continuação que é executada de forma assíncrona quando o Task<TResult> de destino é concluído.
ContinueWith<TResult>(Func<Task,Object,TResult>, Object)	Cria uma continuação que recebe informações de estado fornecidas pelo chamador e é executada de forma assíncrona quando o Task de destino é concluído e retorna um valor. (Herdado de Task)
ContinueWith<TResult>(Func<Task,Object,TResult>, Object, CancellationToken)	Cria uma continuação que é executada de forma assíncrona quando o Task de destino é concluído e retorna um valor. A continuação recebe informações de estado fornecidas pelo chamador e um token de cancelamento. (Herdado de Task)
ContinueWith<TResult>(Func<Task,Object,TResult>, Object, CancellationToken, TaskContinuationOptions, TaskScheduler)	Cria uma continuação que é executada com base nas opções de continuação de tarefa especificadas quando o Task de destino é concluído e retorna um valor. A continuação recebe informações de estado fornecidas pelo chamador e um token de cancelamento e usa o agendador especificado. (Herdado de Task)
ContinueWith<TResult>(Func<Task,Object,TResult>, Object, TaskContinuationOptions)	Cria uma continuação que é executada com base nas opções de continuação de tarefa especificadas quando o Task de destino é concluído. A continuação recebe informações de estado fornecidas pelo chamador. (Herdado de Task)
ContinueWith<TResult>(Func<Task,Object,TResult>, Object, TaskScheduler)	Cria uma continuação que é executada de forma assíncrona quando o Task de destino é concluído. A continuação recebe informações de estado fornecidas pelo chamador e usa um agendador especificado. (Herdado de Task)
ContinueWith<TResult>(Func<Task,TResult>)	Cria uma continuação que é executada de forma assíncrona quando o Task<TResult> de destino é concluído e retorna um valor. (Herdado de Task)
ContinueWith<TResult>(Func<Task,TResult>, CancellationToken)	Cria uma continuação que é executada de forma assíncrona quando o Task de destino é concluído e retorna um valor. A continuação recebe um token de cancelamento. (Herdado de Task)
ContinueWith<TResult>(Func<Task,TResult>, CancellationToken, TaskContinuationOptions, TaskScheduler)	Cria uma continuação que é executada de acordo com as opções de continuação especificadas e retorna um valor. A continuação é passada por um token de cancelamento e usa um agendador especificado. (Herdado de Task)
ContinueWith<TResult>(Func<Task,TResult>, TaskContinuationOptions)	Cria uma continuação que é executada de acordo com as opções de continuação especificadas e retorna um valor. (Herdado de Task)
ContinueWith<TResult>(Func<Task,TResult>, TaskScheduler)	Cria uma continuação que é executada de forma assíncrona quando o Task de destino é concluído e retorna um valor. A continuação usa um agendador especificado. (Herdado de Task)
Dispose()	Libera todos os recursos usados pela instância atual da classe Task. (Herdado de Task)
Dispose(Boolean)	Descarta o Task, liberando todos os seus recursos não gerenciados. (Herdado de Task)
Equals(Object)	Determina se o objeto especificado é igual ao objeto atual. (Herdado de Object)
GetAwaiter()	Obtém um aguardador usado para aguardar este Task<TResult>.
GetHashCode()	Serve como a função de hash padrão. (Herdado de Object)
GetType()	Obtém o Type da instância atual. (Herdado de Object)
MemberwiseClone()	Cria uma cópia superficial do Objectatual. (Herdado de Object)
RunSynchronously()	Executa o Task de forma síncrona no TaskScheduleratual. (Herdado de Task)
RunSynchronously(TaskScheduler)	Executa o Task de forma síncrona no TaskScheduler fornecido. (Herdado de Task)
Start()	Inicia o Task, agendando-o para execução no TaskScheduleratual. (Herdado de Task)
Start(TaskScheduler)	Inicia o Task, agendando-o para execução no TaskSchedulerespecificado. (Herdado de Task)
ToString()	Retorna uma cadeia de caracteres que representa o objeto atual. (Herdado de Object)
Wait()	Aguarda o Task concluir a execução. (Herdado de Task)
Wait(CancellationToken)	Aguarda o Task concluir a execução. A espera será encerrada se um token de cancelamento for cancelado antes da conclusão da tarefa. (Herdado de Task)
Wait(Int32)	Aguarda que o Task conclua a execução dentro de um número especificado de milissegundos. (Herdado de Task)
Wait(Int32, CancellationToken)	Aguarda o Task concluir a execução. A espera termina se um intervalo de tempo limite decorrido ou um token de cancelamento for cancelado antes da conclusão da tarefa. (Herdado de Task)
Wait(TimeSpan)	Aguarda que o Task conclua a execução dentro de um intervalo de tempo especificado. (Herdado de Task)
Wait(TimeSpan, CancellationToken)	Aguarda o Task concluir a execução. (Herdado de Task)
WaitAsync(CancellationToken)	Obtém um Task<TResult> que será concluído quando esse Task<TResult> for concluído ou quando o CancellationToken especificado tiver o cancelamento solicitado.
WaitAsync(TimeSpan)	Obtém um Task<TResult> que será concluído quando esse Task<TResult> for concluído ou quando o tempo limite especificado expirar.
WaitAsync(TimeSpan, CancellationToken)	Obtém um Task<TResult> que será concluído quando esse Task<TResult> for concluído, quando o tempo limite especificado expirar ou quando o CancellationToken especificado tiver o cancelamento solicitado.
WaitAsync(TimeSpan, TimeProvider)	Obtém um Task<TResult> que será concluído quando esse Task<TResult> for concluído ou quando o tempo limite especificado expirar.
WaitAsync(TimeSpan, TimeProvider, CancellationToken)	Obtém um Task<TResult> que será concluído quando esse Task<TResult> for concluído, quando o tempo limite especificado expirar ou quando o CancellationToken especificado tiver o cancelamento solicitado.

Implantações explícitas de interface

IAsyncResult.AsyncWaitHandle	Obtém um WaitHandle que pode ser usado para aguardar a conclusão da tarefa. (Herdado de Task)
IAsyncResult.CompletedSynchronously	Obtém uma indicação de se a operação foi concluída de forma síncrona. (Herdado de Task)

Métodos de Extensão

WaitAsync(Task, TimeSpan, TimeProvider, CancellationToken)	Obtém um Task que será concluído quando esse Task for concluído, quando o tempo limite especificado expirar ou quando o CancellationToken especificado tiver o cancelamento solicitado.
WaitAsync<TResult>(Task<TResult>, TimeSpan, TimeProvider, CancellationToken)	Obtém um Task que será concluído quando esse Task for concluído, quando o tempo limite especificado expirar ou quando o CancellationToken especificado tiver o cancelamento solicitado.

Acesso thread-safe

Todos os membros de Task<TResult>, exceto Dispose(), são thread-safe e podem ser usados de vários threads simultaneamente.

Confira também

• Task
• da TPL (Biblioteca Paralela de Tarefas)
• de programação assíncrona baseada em tarefa
• exemplos de programação paralela com o .NET Core e o .NET Standard