TPL 和传统 .NET 异步编程TPL and traditional .NET asynchronous programming

.NET 提供了以下两种标准模式,用于执行 I/O 密集型和计算密集型异步操作:.NET provides the following two standard patterns for performing I/O-bound and compute-bound asynchronous operations:

任务并行库 (TPL) 可采用各种方法与任一异步模式协同使用。The Task Parallel Library (TPL) can be used in various ways in conjunction with either of the asynchronous patterns. 可将 APM 和 EAP 操作作为 Task 对象向库使用者公开,也可以公开 APM 模式但用 Task 对象在内部实现它们。You can expose both APM and EAP operations as Task objects to library consumers, or you can expose the APM patterns but use Task objects to implement them internally. 在这两种情况下,可使用 Task 对象简化代码以及利用以下有用的功能:In both scenarios, by using Task objects, you can simplify the code and take advantage of the following useful functionality:

  • 在任务开始后随时以任务延续形式注册回调。Register callbacks, in the form of task continuations, at any time after the task has started.

  • 使用 ContinueWhenAllContinueWhenAny 方法,或者 WaitAllWaitAny 方法并列为响应 Begin_ 方法而执行的多个操作。Coordinate multiple operations that execute in response to a Begin_ method by using the ContinueWhenAll and ContinueWhenAny methods, or the WaitAll and WaitAny methods.

  • 封装同一 Task 对象中的异步 I/O 密集型和计算密集型操作。Encapsulate asynchronous I/O-bound and compute-bound operations in the same Task object.

  • 监视 Task 对象的状态。Monitor the status of the Task object.

  • 使用 TaskCompletionSource<TResult> 将操作状态封送处理至 Task 对象。Marshal the status of an operation to a Task object by using TaskCompletionSource<TResult>.

在 Task 中包装 APM 操作Wrap APM operations in a Task

System.Threading.Tasks.TaskFactorySystem.Threading.Tasks.TaskFactory<TResult> 类都提供了 TaskFactory.FromAsyncTaskFactory<TResult>.FromAsync 方法的几个重载,由此可将 APM begin/end 方法对封装在 TaskTask<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. 各种重载都可容纳任何具有零至三个输入参数的 begin/end 方法对。The various overloads accommodate any begin/end method pair that have from zero to three input parameters.

对于具有返回值(在 Visual Basic 中为 Function)的 End 方法的对,使用 TaskFactory<TResult> 中创建 Task<TResult> 的方法。For pairs that have End methods that return a value (a Function in Visual Basic), use the methods in TaskFactory<TResult> that create a Task<TResult>. 对于具有返回 void(在 Visual Basic 中为 Sub)的 End 方法,使用 TaskFactory 中创建 Task 的方法。For End methods that return void (a Sub in Visual Basic), use the methods in TaskFactory that create a Task.

在极少情况下,如果 Begin 方法具有三个以上参数或包含 refout 参数,则提供仅封装 End 方法的其他 FromAsync 重载。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.

下面的示例显示了匹配 FileStream.BeginReadFileStream.EndRead 方法的 FromAsync 重载的签名。The following example shows the signature for the FromAsync overload that matches the FileStream.BeginRead and FileStream.EndRead methods.

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)

此重载采用三个输入参数,如下所示。This overload takes three input parameters, as follows. 第一个参数是匹配 FileStream.BeginRead 方法签名的 Func<T1,T2,T3,T4,T5,TResult> 委托。The first parameter is a Func<T1,T2,T3,T4,T5,TResult> delegate that matches the signature of the FileStream.BeginRead method. 第二个参数使用 IAsyncResult 并返回 TResultFunc<T,TResult> 委托。The second parameter is a Func<T,TResult> delegate that takes an IAsyncResult and returns a TResult. 由于 EndRead 返回一个整数,因此编译器会将 TResult 类型推断为 Int32 并将任务类型推断为 TaskBecause EndRead returns an integer, the compiler infers the type of TResult as Int32 and the type of the task as Task. 最后第四个参数与 FileStream.BeginRead 方法中的参数相同:The last four parameters are identical to those in the FileStream.BeginRead method:

  • 存储文件数据的缓冲区。The buffer in which to store the file data.

  • 开始写入数据的缓冲区的偏移量。The offset in the buffer at which to begin writing data.

  • 要从文件中读取的最大数据量。The maximum amount of data to read from the file.

  • 存储要传递至回调的用户定义状态数据的可选对象。An optional object that stores user-defined state data to pass to the callback.

使用 ContinueWith 执行回调功能Use ContinueWith for the callback functionality

如果需要访问文件中的数据,而不仅仅访问字节数,则 FromAsync 方法不能满足此操作。If you require access to the data in the file, as opposed to just the number of bytes, the FromAsync method is not sufficient. 请改用 Task,其 Result 属性包含文件数据。Instead, use Task, whose Result property contains the file data. 可以通过向原始任务添加延续来实现这种操作。You can do this by adding a continuation to the original task. 延续执行通常由 AsyncCallback 委托执行的任务。The continuation performs the work that would typically be performed by the AsyncCallback delegate. 先前任务完成且填充了数据缓冲区后调用此操作。It is invoked when the antecedent completes, and the data buffer has been filled. FileStream 对象应在返回前关闭。)(The FileStream object should be closed before returning.)

下面的示例演示如何返回封装 FileStream 类的 BeginRead/EndRead 对的 TaskThe 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 - 1) 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

然后可调用此方法,如下所示。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

提供自定义状态数据Provide custom state data

在通常的 IAsyncResult 操作中,如果AsyncCallback 委托需要一些自定义状态数据,则必须通过 Begin 方法中的最后一个参数将它传入,以便可将数据打包到最终要传递至回调方法的 IAsyncResult 对象中。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. 当使用 FromAsync 方法时,通常无需此操作。This is typically not required when the FromAsync methods are used. 如果延续知道自定义数据,可直接在延续委托中捕获它。If the custom data is known to the continuation, then it can be captured directly in the continuation delegate. 下面的示例与以前的示例类似,但延续检查此延续的用户委托可直接访问的自定义状态数据,而不是检查历史任务的 Result 属性。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 - 1) 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

同步多个 FromAsync 任务Synchronize multiple FromAsync tasks

当结合使用 FromAsync 方法时,静态 ContinueWhenAllContinueWhenAny 方法具有更大的灵活性。The static ContinueWhenAll and ContinueWhenAny methods provide added flexibility when used in conjunction with the FromAsync methods. 下面的示例显示如何启动多个异步 I/O 操作,然后等待所有这些操作都完成后再执行延续。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 - 1) 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

仅用于 End 方法的 FromAsync 任务FromAsync tasks for only the End method

在极少情况下,如果 Begin 方法需要三个以上的输入参数,或具有 refout 参数,可以使用仅表示 End 方法的 FromAsync 重载,例如,TaskFactory<TResult>.FromAsync(IAsyncResult, Func<IAsyncResult,TResult>)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. 这些方法还可用于传递 IAsyncResult 并将其封装到 Task 的任何方案中。These methods can also be used in any scenario in which you're 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

开始和取消 FromAsync 任务Start and cancel FromAsync tasks

FromAsync 方法返回的任务具有 WaitingForActivation 状态,并在创建任务后在某个时刻由操作系统启动。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. 如果尝试调用此类任务上的“启动”,将引发异常。If you attempt to call Start on such a task, an exception will be raised.

无法取消 FromAsync 任务,因为基础 .NET API 目前不支持取消正在进行中的文件或网络 I/O。You cannot cancel a FromAsync task, because the underlying .NET APIs currently do not support in-progress cancellation of file or network I/O. 可以将取消功能添加到封装 FromAsync 调用的方法中,但只能在调用 FromAsync 之前或在调用完成之后响应取消(例如,在延续任务中)。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).

一些支持 EAP 的类(如 WebClient)不支持取消,但可以通过使用取消标记集成该本机取消功能。Some classes that support EAP, for example, WebClient, do support cancellation, and you can integrate that native cancellation functionality by using cancellation tokens.

将复杂的 EAP 操作公开为任务Expose complex EAP operations As tasks

TPL 不提供任何专用于以 FromAsync 系列方法包装 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. 但是,TPL 会提供 System.Threading.Tasks.TaskCompletionSource<TResult> 类,此类可用于将任意一组操作表示为 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>. 这些操作可能同步、可能异步,可能是 I/O 密集型、也可能是计算密集型,还可能两者都是。The operations may be synchronous or asynchronous, and may be I/O bound or compute-bound, or both.

下面的示例显示如何使用 TaskCompletionSource<TResult> 将一组异步 WebClient 操作作为基础 Task<TResult> 向客户端代码公开。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>. 此方法允许输入 Web URL 数组和术语或名称来进行搜索,然后返回每个站点搜索字词出现的次数。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

有关包括其他异常处理且展示了如何通过客户端代码调用方法的更完整示例,请参阅如何:在任务中包装 EAP 模式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.

请记住,通过 TaskCompletionSource<TResult> 创建的任何任务均由 TaskCompletionSource 启动,因此用户代码不应在此任务中调用 Start 方法。Remember that any task that's created by a TaskCompletionSource<TResult> will be started by that TaskCompletionSource and, therefore, user code should not call the Start method on that task.

使用任务实现 APM 模式Implement the APM pattern by using tasks

在某些情况下,可能需要通过使用 API 中 begin/end 方法对直接公开 IAsyncResult 模式。In some scenarios, it may be desirable to directly expose the IAsyncResult pattern by using begin/end method pairs in an API. 例如,可能想要与现有的 API 保持一致,或者可能具有需要这种模式的自动化工具。For example, you may want to maintain consistency with existing APIs, or you may have automated tools that require this pattern. 在这种情况下,可使用 Task 对象来简化在内部实现 APM 模式的方式。In such cases, you can use Task objects to simplify how the APM pattern is implemented internally.

下面的示例显示如何使用任务实现长时间运行计算密集型方法的 APM begin/end 方法对。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

使用 StreamExtensions 示例代码Use the StreamExtensions sample code

.NET Standard parallel extensions extras 存储库中的 StreamExtensions.cs 文件包含将 Task 对象用于异步文件和网络 I/O 的若干参考实现。The StreamExtensions.cs file, in the .NET Standard parallel extensions extras repository, contains several reference implementations that use Task objects for asynchronous file and network I/O.

请参阅See also