TPL y la programación asincrónica tradicional de .NET FrameworkTPL and Traditional .NET Framework Asynchronous Programming

.NET Framework proporciona los siguientes dos modelos estándar para realizar las operaciones asincrónicas enlazadas a E/S y enlazadas a cálculos:The .NET Framework provides the following two standard patterns for performing I/O-bound and compute-bound asynchronous operations:

  • Modelo de programación asincrónica (APM), en el que las operaciones asincrónicas se representan mediante un par de métodos Begin/End como FileStream.BeginRead y Stream.EndRead.Asynchronous Programming Model (APM), in which asynchronous operations are represented by a pair of Begin/End methods such as FileStream.BeginRead and Stream.EndRead.

  • Modelo asincrónico basado en eventos (EAP) en el que las operaciones asincrónicas se representan mediante un par método-evento que se denomina OperationNameAsync y OperationNameCompleted; por ejemplo, WebClient.DownloadStringAsync y WebClient.DownloadStringCompleted.Event-based asynchronous pattern (EAP), in which asynchronous operations are represented by a method/event pair that are named OperationNameAsync and OperationNameCompleted, for example, WebClient.DownloadStringAsync and WebClient.DownloadStringCompleted. (EAP apareció por primera vez en .NET Framework versión 2.0).(EAP was introduced in the .NET Framework version 2.0.)

La biblioteca TPL (Task Parallel Library, biblioteca de procesamiento paralelo basado en tareas) se puede usar de varias maneras junto con cualquiera de los modelos asincrónicos.The Task Parallel Library (TPL) can be used in various ways in conjunction with either of the asynchronous patterns. Puede exponer las operaciones de APM y EAP como tareas a los consumidores de la biblioteca o puede exponer los modelos de APM, pero usar objetos de tarea para implementarlos internamente.You can expose both APM and EAP operations as Tasks to library consumers, or you can expose the APM patterns but use Task objects to implement them internally. En ambos escenarios, al usar los objetos de tarea, puede simplificar el código y aprovechar la siguiente funcionalidad útil:In both scenarios, by using Task objects, you can simplify the code and take advantage of the following useful functionality:

  • Registre las devoluciones de llamada, en el formulario de continuaciones de la tarea, en cualquier momento después de que se haya iniciado la tarea.Register callbacks, in the form of task continuations, at any time after the task has started.

  • Coordine varias operaciones que se ejecutan en respuesta a un método Begin_, mediante los métodos ContinueWhenAll, ContinueWhenAny, WaitAll o WaitAny.Coordinate multiple operations that execute in response to a Begin_ method, by using the ContinueWhenAll and ContinueWhenAny methods, or the WaitAll method or the WaitAny method.

  • Encapsule las operaciones asincrónicas enlazadas a E/S y enlazadas a cálculos en el mismo objeto de tarea.Encapsulate asynchronous I/O-bound and compute-bound operations in the same Task object.

  • Supervise el estado del objeto de tarea.Monitor the status of the Task object.

  • Serialice las referencias del estado una operación para un objeto de tarea mediante TaskCompletionSource<TResult>.Marshal the status of an operation to a Task object by using TaskCompletionSource<TResult>.

Ajustar las operaciones de APM en una tareaWrapping APM Operations in a Task

Las clases System.Threading.Tasks.TaskFactory y System.Threading.Tasks.TaskFactory<TResult> proporcionan varias sobrecargas de los métodosTaskFactory.FromAsync yTaskFactory<TResult>.FromAsyncque permiten encapsular un par de métodos Begin/End en una instancia Task o Task<TResult>.Both the System.Threading.Tasks.TaskFactory and System.Threading.Tasks.TaskFactory<TResult> classes provide several overloads of the TaskFactory.FromAsync and TaskFactory<TResult>.FromAsync methods that let you encapsulate an APM Begin/End method pair in one Task or Task<TResult> instance. Las diversas sobrecargas hospedan cualquier par de métodos de Begin/End que tenga entre cero y tres parámetros de entrada.The various overloads accommodate any Begin/End method pair that have from zero to three input parameters.

Para los pares que tienen métodos End que devuelven un valor (Function en Visual Basic), use los métodos de TaskFactory<TResult> que crean un objeto Task<TResult>.For pairs that have End methods that return a value (Function in Visual Basic), use the methods in TaskFactory<TResult> that create a Task<TResult>. Para los métodos End que devuelven un valor void (Sub en Visual Basic), use los métodos de TaskFactory que crean un objeto Task.For End methods that return void (Sub in Visual Basic), use the methods in TaskFactory that create a Task.

En los pocos casos en los que el método Begin tiene más de tres parámetros o contiene parámetros ref o out, se proporcionan las sobrecargas FromAsync adicionales que encapsulan sólo el método End.For those few cases in which the Begin method has more than three parameters or contains ref or out parameters, additional FromAsync overloads that encapsulate only the End method are provided.

En el ejemplo siguiente, se muestra la signatura para la sobrecarga FromAsync que coincide con los métodos FileStream.BeginRead y FileStream.EndRead.The following example shows the signature for the FromAsync overload that matches the FileStream.BeginRead and FileStream.EndRead methods. Esta sobrecarga toma los tres parámetros de entrada siguientes.This overload takes three input parameters, as follows.

public Task<TResult> FromAsync<TArg1, TArg2, TArg3>(
    Func<TArg1, TArg2, TArg3, AsyncCallback, object, IAsyncResult> beginMethod, //BeginRead
     Func<IAsyncResult, TResult> endMethod, //EndRead
     TArg1 arg1, // the byte[] buffer
     TArg2 arg2, // the offset in arg1 at which to start writing data
     TArg3 arg3, // the maximum number of bytes to read
     object state // optional state information
    ) 
Public Function FromAsync(Of TArg1, TArg2, TArg3)(
                ByVal beginMethod As Func(Of TArg1, TArg2, TArg3, AsyncCallback, Object, IAsyncResult),
                ByVal endMethod As Func(Of IAsyncResult, TResult),
                ByVal dataBuffer As TArg1,
                ByVal byteOffsetToStartAt As TArg2,
                ByVal maxBytesToRead As TArg3,
                ByVal stateInfo As Object)

El primer parámetro es un delegado Func<T1,T2,T3,T4,T5,TResult> que coincide con la signatura del método FileStream.BeginRead.The first parameter is a Func<T1,T2,T3,T4,T5,TResult> delegate that matches the signature of the FileStream.BeginRead method. El segundo parámetro es un delegado Func<T,TResult> que toma una interfaz IAsyncResult y devuelve TResult.The second parameter is a Func<T,TResult> delegate that takes an IAsyncResult and returns a TResult. Dado que EndRead devuelve un entero, el compilador deduce el tipo de TResult como Int32 y el tipo de la tarea como Task.Because EndRead returns an integer, the compiler infers the type of TResult as Int32 and the type of the task as Task. Los últimos cuatro parámetros son idénticos a los del método FileStream.BeginRead:The last four parameters are identical to those in the FileStream.BeginRead method:

  • Búfer donde se van a almacenar los datos de archivo.The buffer in which to store the file data.

  • Desplazamiento en el búfer donde deben comenzar a escribirse los datos.The offset in the buffer at which to begin writing data.

  • Cantidad máxima de datos que se van a leer del archivo.The maximum amount of data to read from the file.

  • Un objeto opcional que almacena los datos de estado definidos por el usuario que se van a pasar a la devolución de llamada.An optional object that stores user-defined state data to pass to the callback.

Usar ContinueWith para la funcionalidad de devolución de llamadaUsing ContinueWith for the Callback Functionality

Si necesita obtener acceso a los datos del archivo, en contraposición a solo el número de bytes, el método FromAsync no es suficiente.If you require access to the data in the file, as opposed to just the number of bytes, the FromAsync method is not sufficient. En su ligar, use Task, cuya propiedad Result contiene los datos de archivo.Instead, use Task, whose Result property contains the file data. Puede hacer si agrega una continuación a la tarea original.You can do this by adding a continuation to the original task. La continuación realiza el trabajo que normalmente realizaría el delegado AsyncCallback.The continuation performs the work that would typically be performed by the AsyncCallback delegate. Se invoca cuando se completa el antecedente y se ha rellenado el búfer de datos.It is invoked when the antecedent completes, and the data buffer has been filled. (El objeto FileStream se debería cerrar antes de devolver un valor).(The FileStream object should be closed before returning.)

En el siguiente ejemplo se muestra cómo devolver un objeto Task que encapsula el par BeginRead/EndRead de la clase FileStream.The following example shows how to return a Task that encapsulates the BeginRead/EndRead pair of the FileStream class.

const int MAX_FILE_SIZE = 14000000;
public static Task<string> GetFileStringAsync(string path)
{
    FileInfo fi = new FileInfo(path);
    byte[] data = null;
    data = new byte[fi.Length];

    FileStream fs = new FileStream(path, FileMode.Open, FileAccess.Read, FileShare.Read, data.Length, true);

    //Task<int> returns the number of bytes read
    Task<int> task = Task<int>.Factory.FromAsync(
            fs.BeginRead, fs.EndRead, data, 0, data.Length, null);

    // It is possible to do other work here while waiting
    // for the antecedent task to complete.
    // ...

    // Add the continuation, which returns a Task<string>. 
    return task.ContinueWith((antecedent) =>
    {
        fs.Close();

        // Result = "number of bytes read" (if we need it.)
        if (antecedent.Result < 100)
        {
            return "Data is too small to bother with.";
        }
        else
        {
            // If we did not receive the entire file, the end of the
            // data buffer will contain garbage.
            if (antecedent.Result < data.Length)
                Array.Resize(ref data, antecedent.Result);

            // Will be returned in the Result property of the Task<string>
            // at some future point after the asynchronous file I/O operation completes.
            return new UTF8Encoding().GetString(data);
        }
    });
}
Const MAX_FILE_SIZE As Integer = 14000000
Shared Function GetFileStringAsync(ByVal path As String) As Task(Of String)
    Dim fi As New FileInfo(path)
    Dim data(fi.Length) As Byte

    Dim fs As FileStream = New FileStream(path, FileMode.Open, FileAccess.Read, FileShare.Read, data.Length, True)

    ' Task(Of Integer) returns the number of bytes read
    Dim myTask As Task(Of Integer) = Task(Of Integer).Factory.FromAsync(
        AddressOf fs.BeginRead, AddressOf fs.EndRead, data, 0, data.Length, Nothing)

    ' It is possible to do other work here while waiting
    ' for the antecedent task to complete.
    ' ...

    ' Add the continuation, which returns a Task<string>. 
    Return myTask.ContinueWith(Function(antecedent)
                                   fs.Close()
                                   If (antecedent.Result < 100) Then
                                       Return "Data is too small to bother with."
                                   End If
                                   ' If we did not receive the entire file, the end of the
                                   ' data buffer will contain garbage.
                                   If (antecedent.Result < data.Length) Then
                                       Array.Resize(data, antecedent.Result)
                                   End If

                                   ' Will be returned in the Result property of the Task<string>
                                   ' at some future point after the asynchronous file I/O operation completes.
                                   Return New UTF8Encoding().GetString(data)
                               End Function)

End Function

A continuación, se puede llamar al método de la forma siguiente.The method can then be called, as follows.


 Task<string> t = GetFileStringAsync(path);          

 // Do some other work:
 // ...

 try
 {
      Console.WriteLine(t.Result.Substring(0, 500));
 }
 catch (AggregateException ae)
 {
     Console.WriteLine(ae.InnerException.Message);
 }            
Dim myTask As Task(Of String) = GetFileStringAsync(path)

' Do some other work
' ...

Try
    Console.WriteLine(myTask.Result.Substring(0, 500))
Catch ex As AggregateException
    Console.WriteLine(ex.InnerException.Message)
End Try

Proporcionar los datos de estado personalizadosProviding Custom State Data

En las operaciones IAsyncResult típicas, si el delegado AsyncCallback requiere algún dato de estado personalizado, tiene que pasarlo a través del último parámetro Begin para que los datos se puedan empaquetar en el objeto IAsyncResult que se pasará finalmente al método de devolución de llamada.In typical IAsyncResult operations, if your AsyncCallback delegate requires some custom state data, you have to pass it in through the last parameter in the Begin method, so that the data can be packaged into the IAsyncResult object that is eventually passed to the callback method. Normalmente no se requiere esto cuando se usan los métodos FromAsync.This is typically not required when the FromAsync methods are used. Si los datos personalizados son conocidos para la continuación, se pueden capturar directamente en el delegado de continuación.If the custom data is known to the continuation, then it can be captured directly in the continuation delegate. El siguiente ejemplo se parece el ejemplo anterior, pero en lugar de examinar la propiedad Result del antecedente, la continuación examina los datos de estado personalizados que son directamente accesibles al delegado de usuario de la continuación.The following example resembles the previous example, but instead of examining the Result property of the antecedent, the continuation examines the custom state data that is directly accessible to the user delegate of the continuation.

public Task<string> GetFileStringAsync2(string path)
{             
    FileInfo fi = new FileInfo(path);
    byte[] data = new byte[fi.Length];                       
    MyCustomState state = GetCustomState();
    FileStream fs = new FileStream(path, FileMode.Open, FileAccess.Read, FileShare.Read, data.Length, true);
    // We still pass null for the last parameter because
    // the state variable is visible to the continuation delegate.
    Task<int> task = Task<int>.Factory.FromAsync(
            fs.BeginRead, fs.EndRead, data, 0, data.Length, null);

    return task.ContinueWith((antecedent) =>
    {
        // It is safe to close the filestream now.
        fs.Close();

        // Capture custom state data directly in the user delegate.
        // No need to pass it through the FromAsync method.
        if (state.StateData.Contains("New York, New York"))
        {
            return "Start spreading the news!";
        }
        else
        {
            // If we did not receive the entire file, the end of the
            // data buffer will contain garbage.
            if (antecedent.Result < data.Length)
                Array.Resize(ref data, antecedent.Result);

            // Will be returned in the Result property of the Task<string>
            // at some future point after the asynchronous file I/O operation completes.
            return new UTF8Encoding().GetString(data);
        }
    });
    
}
Public Function GetFileStringAsync2(ByVal path As String) As Task(Of String)
    Dim fi = New FileInfo(path)
    Dim data(fi.Length) As Byte
    Dim state As New MyCustomState()

    Dim fs As New FileStream(path, FileMode.Open, FileAccess.Read, FileShare.Read, data.Length, True)
    ' We still pass null for the last parameter because
    ' the state variable is visible to the continuation delegate.
    Dim myTask As Task(Of Integer) = Task(Of Integer).Factory.FromAsync(
            AddressOf fs.BeginRead, AddressOf fs.EndRead, data, 0, data.Length, Nothing)

    Return myTask.ContinueWith(Function(antecedent)
                                   fs.Close()
                                   ' Capture custom state data directly in the user delegate.
                                   ' No need to pass it through the FromAsync method.
                                   If (state.StateData.Contains("New York, New York")) Then
                                       Return "Start spreading the news!"
                                   End If

                                   ' If we did not receive the entire file, the end of the
                                   ' data buffer will contain garbage.
                                   If (antecedent.Result < data.Length) Then
                                       Array.Resize(data, antecedent.Result)
                                   End If
                                   '/ Will be returned in the Result property of the Task<string>
                                   '/ at some future point after the asynchronous file I/O operation completes.
                                   Return New UTF8Encoding().GetString(data)
                               End Function)

End Function

Sincronizar varias tareas FromAsyncSynchronizing Multiple FromAsync Tasks

Los métodos estáticos ContinueWhenAll y ContinueWhenAny proporcionan flexibilidad adicional cuando se usan junto con los métodos FromAsync.The static ContinueWhenAll and ContinueWhenAny methods provide added flexibility when used in conjunction with the FromAsync methods. El siguiente ejemplo muestra cómo iniciar varias operaciones asincrónicas de E/S y, a continuación, espera a que todos ellas se completen antes de ejecutar la continuación.The following example shows how to initiate multiple asynchronous I/O operations, and then wait for all of them to complete before you execute the continuation.

public Task<string> GetMultiFileData(string[] filesToRead)
{
    FileStream fs;
    Task<string>[] tasks = new Task<string>[filesToRead.Length];
    byte[] fileData = null;
    for (int i = 0; i < filesToRead.Length; i++)
    {
        fileData = new byte[0x1000];
        fs = new FileStream(filesToRead[i], FileMode.Open, FileAccess.Read, FileShare.Read, fileData.Length, true);

        // By adding the continuation here, the 
        // Result of each task will be a string.
        tasks[i] = Task<int>.Factory.FromAsync(
                 fs.BeginRead, fs.EndRead, fileData, 0, fileData.Length, null)
                 .ContinueWith((antecedent) =>
                     {
                         fs.Close();

                         // If we did not receive the entire file, the end of the
                         // data buffer will contain garbage.
                         if (antecedent.Result < fileData.Length)
                             Array.Resize(ref fileData, antecedent.Result);

                         // Will be returned in the Result property of the Task<string>
                         // at some future point after the asynchronous file I/O operation completes.
                         return new UTF8Encoding().GetString(fileData);
                     });
    }

    // Wait for all tasks to complete. 
    return Task<string>.Factory.ContinueWhenAll(tasks, (data) =>
    {
        // Propagate all exceptions and mark all faulted tasks as observed.
        Task.WaitAll(data);

        // Combine the results from all tasks.
        StringBuilder sb = new StringBuilder();
        foreach (var t in data)
        {
            sb.Append(t.Result);
        }
        // Final result to be returned eventually on the calling thread.
        return sb.ToString();
    });

}
Public Function GetMultiFileData(ByVal filesToRead As String()) As Task(Of String)
    Dim fs As FileStream
    Dim tasks(filesToRead.Length) As Task(Of String)
    Dim fileData() As Byte = Nothing
    For i As Integer = 0 To filesToRead.Length
        fileData(&H1000) = New Byte()
        fs = New FileStream(filesToRead(i), FileMode.Open, FileAccess.Read, FileShare.Read, fileData.Length, True)

        ' By adding the continuation here, the 
        ' Result of each task will be a string.
        tasks(i) = Task(Of Integer).Factory.FromAsync(AddressOf fs.BeginRead,
                                                      AddressOf fs.EndRead,
                                                      fileData,
                                                      0,
                                                      fileData.Length,
                                                      Nothing).
                                                  ContinueWith(Function(antecedent)
                                                                   fs.Close()
                                                                   'If we did not receive the entire file, the end of the
                                                                   ' data buffer will contain garbage.
                                                                   If (antecedent.Result < fileData.Length) Then
                                                                       ReDim Preserve fileData(antecedent.Result)
                                                                   End If

                                                                   'Will be returned in the Result property of the Task<string>
                                                                   ' at some future point after the asynchronous file I/O operation completes.
                                                                   Return New UTF8Encoding().GetString(fileData)
                                                               End Function)
    Next

    Return Task(Of String).Factory.ContinueWhenAll(tasks, Function(data)

                                                              ' Propagate all exceptions and mark all faulted tasks as observed.
                                                              Task.WaitAll(data)

                                                              ' Combine the results from all tasks.
                                                              Dim sb As New StringBuilder()
                                                              For Each t As Task(Of String) In data
                                                                  sb.Append(t.Result)
                                                              Next
                                                              ' Final result to be returned eventually on the calling thread.
                                                              Return sb.ToString()
                                                          End Function)
End Function

Tareas FromAsync solo para el método EndFromAsync Tasks For Only the End Method

En los pocos casos en los que el método Begin requiere más de tres parámetros de entrada o tiene parámetros ref o out, puede usar las sobrecargas FromAsync, por ejemplo, TaskFactory<TResult>.FromAsync(IAsyncResult, Func<IAsyncResult,TResult>), que representa sólo el método End.For those few cases in which the Begin method requires more than three input parameters, or has ref or out parameters, you can use the FromAsync overloads, for example, TaskFactory<TResult>.FromAsync(IAsyncResult, Func<IAsyncResult,TResult>), that represent only the End method. Estos métodos también se pueden usar en cualquier escenario en el que se pasa IAsyncResult y desea encapsularlo en una tarea.These methods can also be used in any scenario in which you are passed an IAsyncResult and want to encapsulate it in a Task.

static Task<String> ReturnTaskFromAsyncResult()
{
    IAsyncResult ar = DoSomethingAsynchronously();
    Task<String> t = Task<string>.Factory.FromAsync(ar, _ =>
        {
            return (string)ar.AsyncState;
        });

    return t;
}
Shared Function ReturnTaskFromAsyncResult() As Task(Of String)
    Dim ar As IAsyncResult = DoSomethingAsynchronously()
    Dim t As Task(Of String) = Task(Of String).Factory.FromAsync(ar, Function(res) CStr(res.AsyncState))
    Return t
End Function

Iniciar y cancelar las tareas FromAsyncStarting and Canceling FromAsync Tasks

La tarea devuelta por un método FromAsync tiene un estado de WaitingForActivation y la iniciará el sistema en algún momento una vez creada la tarea.The task returned by a FromAsync method has a status of WaitingForActivation and will be started by the system at some point after the task is created. Si intenta llamar a Start en este tipo de tarea, se producirá una excepción.If you attempt to call Start on such a task, an exception will be raised.

No puede cancelar una tarea FromAsync, porque las API subyacentes de .NET Framework admiten actualmente la cancelación en curso del la E/S de archivo o red.You cannot cancel a FromAsync task, because the underlying .NET Framework APIs currently do not support in-progress cancellation of file or network I/O. Puede agregar la funcionalidad de cancelación a un método que encapsula una llamada FromAsync, pero sólo puede responder a la cancelación antes de que se llame a FromAsync o después de completar (por ejemplo, en una tarea de continuación).You can add cancellation functionality to a method that encapsulates a FromAsync call, but you can only respond to the cancellation before FromAsync is called or after it completed (for example, in a continuation task).

Algunas clases que admiten EAP, por ejemplo, WebClient, admiten la cancelación y esa funcionalidad de cancelación nativa se puede integrar mediante los tokens de cancelación.Some classes that support EAP, for example, WebClient, do support cancellation, and you can integrate that native cancellation functionality by using cancellation tokens.

Exponer las operaciones de EAP complejas como tareasExposing Complex EAP Operations As Tasks

La TPL no proporciona ningún método diseñado específicamente para encapsular una operación asincrónica basada en eventos del mismo modo que la familia de métodos FromAsync ajusta el modelo IAsyncResult.The TPL does not provide any methods that are specifically designed to encapsulate an event-based asynchronous operation in the same way that the FromAsync family of methods wrap the IAsyncResult pattern. Sin embargo, TPL proporciona la clase System.Threading.Tasks.TaskCompletionSource<TResult>, que se puede usar para representar cualquier conjunto arbitrario de operaciones como Task<TResult>.However, the TPL does provide the System.Threading.Tasks.TaskCompletionSource<TResult> class, which can be used to represent any arbitrary set of operations as a Task<TResult>. Las operaciones pueden ser sincrónicas o asincrónicas y pueden ser enlazadas a E/S o enlazadas a cálculo, o ambos.The operations may be synchronous or asynchronous, and may be I/O bound or compute-bound, or both.

En el siguiente ejemplo se muestra cómo usar TaskCompletionSource<TResult> para exponer un conjunto de operaciones WebClient asincrónicas al código de cliente como un objeto Task<TResult> básico.The following example shows how to use a TaskCompletionSource<TResult> to expose a set of asynchronous WebClient operations to client code as a basic Task<TResult>. El método permite escribir una matriz de direcciones URL de web y un término o nombre que se va a buscar y, a continuación, devuelve el número de veces que aparece el término de búsqueda en cada sitio.The method lets you enter an array of Web URLs, and a term or name to search for, and then returns the number of times the search term occurs on each site.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Net;
using System.Threading;
using System.Threading.Tasks;

public class SimpleWebExample
{
  public Task<string[]> GetWordCountsSimplified(string[] urls, string name,
                                                CancellationToken token)
  {
      TaskCompletionSource<string[]> tcs = new TaskCompletionSource<string[]>();
      WebClient[] webClients = new WebClient[urls.Length];
      object m_lock = new object();
      int count = 0;
      List<string> results = new List<string>();

      // If the user cancels the CancellationToken, then we can use the
      // WebClient's ability to cancel its own async operations.
      token.Register(() =>
      {
          foreach (var wc in webClients)
          {
              if (wc != null)
                  wc.CancelAsync();
          }
      });


      for (int i = 0; i < urls.Length; i++)
      {
          webClients[i] = new WebClient();

          #region callback
          // Specify the callback for the DownloadStringCompleted
          // event that will be raised by this WebClient instance.
          webClients[i].DownloadStringCompleted += (obj, args) =>
          {

              // Argument validation and exception handling omitted for brevity.

              // Split the string into an array of words,
              // then count the number of elements that match
              // the search term.
              string[] words = args.Result.Split(' ');
              string NAME = name.ToUpper();
              int nameCount = (from word in words.AsParallel()
                               where word.ToUpper().Contains(NAME)
                               select word)
                              .Count();

              // Associate the results with the url, and add new string to the array that
              // the underlying Task object will return in its Result property.
              lock (m_lock)
              {
                 results.Add(String.Format("{0} has {1} instances of {2}", args.UserState, nameCount, name));

                 // If this is the last async operation to complete,
                 // then set the Result property on the underlying Task.
                 count++;
                 if (count == urls.Length)
                 {
                    tcs.TrySetResult(results.ToArray());
                 }
              }
          };
          #endregion

          // Call DownloadStringAsync for each URL.
          Uri address = null;
          address = new Uri(urls[i]);
          webClients[i].DownloadStringAsync(address, address);

      } // end for

      // Return the underlying Task. The client code
      // waits on the Result property, and handles exceptions
      // in the try-catch block there.
      return tcs.Task;
   }
}
Imports System.Collections.Generic
Imports System.Net
Imports System.Threading
Imports System.Threading.Tasks

Public Class SimpleWebExample
   Dim tcs As New TaskCompletionSource(Of String())
   Dim token As CancellationToken
   Dim results As New List(Of String)
   Dim m_lock As New Object()
   Dim count As Integer
   Dim addresses() As String
   Dim nameToSearch As String
   
   Public Function GetWordCountsSimplified(ByVal urls() As String, ByVal str As String,
                                           ByVal token As CancellationToken) As Task(Of String())
      addresses = urls
      nameToSearch = str
      
      Dim webClients(urls.Length - 1) As WebClient

      ' If the user cancels the CancellationToken, then we can use the
      ' WebClient's ability to cancel its own async operations.
      token.Register(Sub()
                        For Each wc As WebClient In webClients
                           If wc IsNot Nothing Then
                              wc.CancelAsync()
                           End If
                        Next
                     End Sub)

      For i As Integer = 0 To urls.Length - 1
         webClients(i) = New WebClient()

         ' Specify the callback for the DownloadStringCompleted
         ' event that will be raised by this WebClient instance.
         AddHandler webClients(i).DownloadStringCompleted, AddressOf WebEventHandler

         Dim address As New Uri(urls(i))
         ' Pass the address, and also use it for the userToken
         ' to identify the page when the delegate is invoked.
         webClients(i).DownloadStringAsync(address, address)
      Next

      ' Return the underlying Task. The client code
      ' waits on the Result property, and handles exceptions
      ' in the try-catch block there.
      Return tcs.Task
   End Function

   Public Sub WebEventHandler(ByVal sender As Object, ByVal args As DownloadStringCompletedEventArgs)

      If args.Cancelled = True Then
         tcs.TrySetCanceled()
         Return
      ElseIf args.Error IsNot Nothing Then
         tcs.TrySetException(args.Error)
         Return
      Else
         ' Split the string into an array of words,
         ' then count the number of elements that match
         ' the search term.
         Dim words() As String = args.Result.Split(" "c)

         Dim name As String = nameToSearch.ToUpper()
         Dim nameCount = (From word In words.AsParallel()
                          Where word.ToUpper().Contains(name)
                          Select word).Count()

         ' Associate the results with the url, and add new string to the array that
         ' the underlying Task object will return in its Result property.
         SyncLock (m_lock)
            results.Add(String.Format("{0} has {1} instances of {2}", args.UserState, nameCount, nameToSearch))
            count = count + 1
            If (count = addresses.Length) Then
               tcs.TrySetResult(results.ToArray())
            End If
         End SyncLock
      End If
   End Sub
End Class

Para obtener un ejemplo más completo, en donde se incluye control de excepciones adicional y se muestra cómo llamar al método desde código de cliente, vea Procedimiento: Encapsulado de patrones de EAP en una tarea.For a more complete example, which includes additional exception handling and shows how to call the method from client code, see How to: Wrap EAP Patterns in a Task.

Recuerde que TaskCompletionSource iniciará cualquier tarea creada por TaskCompletionSource<TResult> y, por consiguiente, el código de usuario no debería llamar al método Start en esa tarea.Remember that any task that is created by a TaskCompletionSource<TResult> will be started by that TaskCompletionSource and, therefore, user code should not call the Start method on that task.

Implementar el modelo de APM usando las tareasImplementing the APM Pattern By Using Tasks

En algunos escenarios, puede ser deseable exponer directamente el modelo IAsyncResult mediante pares de métodos Begin/End en una API.In some scenarios, it may be desirable to directly expose the IAsyncResult pattern by using Begin/End method pairs in an API. Por ejemplo, quizás desee mantener la coherencia con las API existentes o puede haber automatizado herramientas que requieren este modelo.For example, you may want to maintain consistency with existing APIs, or you may have automated tools that require this pattern. En tales casos, puede usar las tareas para simplificar la forma en que se implementa internamente el modelo de APM.In such cases, you can use Tasks to simplify how the APM pattern is implemented internally.

En el siguiente ejemplo se muestra cómo usar las tareas para implementar un par de métodos Begin/End de APM para un método enlazado a cálculo de ejecución prolongada.The following example shows how to use tasks to implement an APM Begin/End method pair for a long-running compute-bound method.

class Calculator
{
    public IAsyncResult BeginCalculate(int decimalPlaces, AsyncCallback ac, object state)
    {
        Console.WriteLine("Calling BeginCalculate on thread {0}", Thread.CurrentThread.ManagedThreadId);
        Task<string> f = Task<string>.Factory.StartNew(_ => Compute(decimalPlaces), state);
        if (ac != null) f.ContinueWith((res) => ac(f));
        return f;
    }

    public string Compute(int numPlaces)
    {
        Console.WriteLine("Calling compute on thread {0}", Thread.CurrentThread.ManagedThreadId);

        // Simulating some heavy work.
        Thread.SpinWait(500000000);

        // Actual implemenation left as exercise for the reader.
        // Several examples are available on the Web.
        return "3.14159265358979323846264338327950288";
    }

    public string EndCalculate(IAsyncResult ar)
    {
        Console.WriteLine("Calling EndCalculate on thread {0}", Thread.CurrentThread.ManagedThreadId);
        return ((Task<string>)ar).Result;
    }
}

public class CalculatorClient
{
    static int decimalPlaces = 12;
    public static void Main()
    {
        Calculator calc = new Calculator();
        int places = 35;

        AsyncCallback callBack = new AsyncCallback(PrintResult);
        IAsyncResult ar = calc.BeginCalculate(places, callBack, calc);

        // Do some work on this thread while the calulator is busy.
        Console.WriteLine("Working...");
        Thread.SpinWait(500000);
        Console.ReadLine();
    }

    public static void PrintResult(IAsyncResult result)
    {
        Calculator c = (Calculator)result.AsyncState;
        string piString = c.EndCalculate(result);
        Console.WriteLine("Calling PrintResult on thread {0}; result = {1}",
                    Thread.CurrentThread.ManagedThreadId, piString);
    }
}
Class Calculator
    Public Function BeginCalculate(ByVal decimalPlaces As Integer, ByVal ac As AsyncCallback, ByVal state As Object) As IAsyncResult
        Console.WriteLine("Calling BeginCalculate on thread {0}", Thread.CurrentThread.ManagedThreadId)
        Dim myTask = Task(Of String).Factory.StartNew(Function(obj) Compute(decimalPlaces), state)
        myTask.ContinueWith(Sub(antedecent) ac(myTask))

    End Function
    Private Function Compute(ByVal decimalPlaces As Integer)
        Console.WriteLine("Calling compute on thread {0}", Thread.CurrentThread.ManagedThreadId)

        ' Simulating some heavy work.
        Thread.SpinWait(500000000)

        ' Actual implemenation left as exercise for the reader.
        ' Several examples are available on the Web.
        Return "3.14159265358979323846264338327950288"
    End Function

    Public Function EndCalculate(ByVal ar As IAsyncResult) As String
        Console.WriteLine("Calling EndCalculate on thread {0}", Thread.CurrentThread.ManagedThreadId)
        Return CType(ar, Task(Of String)).Result
    End Function
End Class

Class CalculatorClient
    Shared decimalPlaces As Integer
    Shared Sub Main()
        Dim calc As New Calculator
        Dim places As Integer = 35
        Dim callback As New AsyncCallback(AddressOf PrintResult)
        Dim ar As IAsyncResult = calc.BeginCalculate(places, callback, calc)

        ' Do some work on this thread while the calulator is busy.
        Console.WriteLine("Working...")
        Thread.SpinWait(500000)
        Console.ReadLine()
    End Sub

    Public Shared Sub PrintResult(ByVal result As IAsyncResult)
        Dim c As Calculator = CType(result.AsyncState, Calculator)
        Dim piString As String = c.EndCalculate(result)
        Console.WriteLine("Calling PrintResult on thread {0}; result = {1}",
                   Thread.CurrentThread.ManagedThreadId, piString)
    End Sub

End Class

Usar el código de ejemplo de StreamExtensionsUsing the StreamExtensions Sample Code

El archivo Streamextensions.cs, en Samples for Parallel Programming with the .NET Framework 4 (Ejemplos de programación en paralelo con .NET Framework 4), contiene varias implementaciones de la referencia que usan los objetos de tarea para la E/S asincrónica de archivo y red.The Streamextensions.cs file, in Samples for Parallel Programming with the .NET Framework 4, contains several reference implementations that use Task objects for asynchronous file and network I/O.

Vea tambiénSee also