TPL 和傳統 .NET 的非同步程式設計
.NET 提供下列兩個標準模式執行 I/O 繫結程序和計算繫結程序的非同步作業：
非同步程式設計模型 (APM)，在這個模式中非同步作業會以一對 begin/end 方法表示。 例如：FileStream.BeginRead 和 Stream.EndRead。
事件式非同步模式 (EAP)，在這個模式中非同步作業會以一對名為
<OperationName>Async和<OperationName>Completed的方法/事件配對表示。 例如：WebClient.DownloadStringAsync 和 WebClient.DownloadStringCompleted。
工作平行程式庫 (TPL) 可以用各種方式搭配非同步模式的其中一種。 您可以將 APM 和 EAP 作業作為 Task 物件公開給程式庫的取用者，或公開 APM 模式，但使用 Task 物件在內部進行實作。 在這兩種案例，您可以使用 Task 物件簡化程式碼，並利用下列好用的功能：
在啟動工作的任何時間之後，註冊工作接續形式的回呼。
使用 ContinueWhenAll 和 ContinueWhenAny 方法，或 WaitAll 和 WaitAny 方法協調多項為回應
Begin_方法而執行的作業。在相同
Task物件中封裝非同步 I/O 繫結和計算繫結的作業。監視
Task物件的狀態。使用 TaskCompletionSource<TResult> 封送處理作業狀態給
Task物件。
在工作中包裝 APM 作業
System.Threading.Tasks.TaskFactory 和 System.Threading.Tasks.TaskFactory<TResult> 類別都會提供數個 TaskFactory.FromAsync 和 TaskFactory<TResult>.FromAsync 方法的多載，可讓您封裝 Task 或 Task<TResult> 執行個體的其中一種 APM begin/end 方法組。 這幾種多載會容納具有零到三個輸入參數的任何 begin/end 方法組。
對於具有會傳回值的 End 方法組 (在 Visual Basic 中為 Function)，請使用會建立 Task<TResult> 之 TaskFactory<TResult> 中的方法。 對於會傳回 void 的 End 方法 (在 Visual Basic 中為 Sub)，請使用會建立 Task 之 TaskFactory 中的方法。
在 Begin 方法有三個以上的參數，或是包含 ref 或 out 參數的少數情況下，會提供其他僅封裝 End 方法的 FromAsync 多載。
下列範例示範 FromAsync 多載的簽章，該多載會比對 FileStream.BeginRead 和 FileStream.EndRead 方法。
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)
這個多載會採用三個輸入參數，如下所示。 第一個參數是 Func<T1,T2,T3,T4,T5,TResult> 委派，這與 FileStream.BeginRead 方法的簽章相符。 第二個參數是 Func<T,TResult> 委派，會取得 IAsyncResult 並傳回 TResult。 因為 EndRead 會傳回整數，所以編譯器會推斷 TResult 的類型為 Int32，並且推斷工作的類型為 Task。 最後四個參數和在 FileStream.BeginRead 方法中的相同：
用來儲存檔案資料的緩衝區。
開始寫入資料的緩衝區之位移。
從檔案讀取的資料數量上限。
選擇性的物件，其中儲存要傳遞至回呼的使用者定義狀態資料。
對於回呼功能使用 ContinueWith
如果您需要在檔案中資料的存取權，而不只是需要位元組數，則 FromAsync 方法仍不足夠。 請改用 Task，其 Result 屬性包含檔案資料。 您可將接續加入原始工作來達到此目的。 接續會執行通常由 AsyncCallback 委派所執行的工作。 當前項完成，而且資料緩衝區已滿時，則會叫用它。 (FileStream 物件應該在傳回之前關閉。)
下列範例示範如何傳回 Task，這會封裝 FileStream 類別的 BeginRead/EndRead 組。
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
然後可以呼叫此方法，如下所示。
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
提供自訂狀態資料
在一般 IAsyncResult 作業中，如果您的 AsyncCallback 委派需要一些自訂狀態資料，則您必須透過 Begin 方法中的最後一個參數傳遞它，以便資料可以封裝到 IAsyncResult 物件，而該物件最終會傳遞至回呼方法。 當使用 FromAsync 方法時，這通常不必要。 如果自訂資料對接續為已知，則可以直接在接續委派中擷取。 下列範例類似上述範例，但不檢查前項的 Result 屬性，接續會檢查自訂狀態資料，此為接續的使用者委派所直接存取。
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 工作
當搭配 FromAsync 方法使用時，靜態 ContinueWhenAll 和 ContinueWhenAny 方法會提供額外的彈性。 下列範例示範如何初始化多個非同步 I/O 作業，然後等候它們全部完成，才執行接續。
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 工作
在 Begin 方法需要三個以上輸入參數，或是具有 ref 或 out 參數的少數情況下，您可以使用 FromAsync 多載，例如 TaskFactory<TResult>.FromAsync(IAsyncResult, Func<IAsyncResult,TResult>)，這只會代表 End 方法。 這些方法也可用在當您傳遞 IAsyncResult 且想要將其封裝在工作中的任何情況下。
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 工作
FromAsync 方法所傳回的工作具有 WaitingForActivation 狀態，並且會在工作建立之後由系統在某個時間點啟動。 如果您嘗試呼叫這類工作上的 Start，就會引發例外狀況。
您不能取消 FromAsync 工作，因為基礎 .NET API 目前不支援檔案或網路 I/O 的進行中取消。 您可以加入取消功能到封裝 FromAsync 呼叫的方法，但是您只可以在 FromAsync 呼叫之前或完成之後回應取消 (例如在接續工作中)。
有些類別支援 EAP，例如 WebClient 支援取消，您可以使用取消語彙基元整合該原生的取消功能。
將複雜的 EAP 作業公開為工作
TPL 不提供任何專門用來封裝事件架構非同步作業的方法，和 FromAsync 系列方法包裝 IAsyncResult 模式的方式相同。 但是，TPL 並不提供 System.Threading.Tasks.TaskCompletionSource<TResult> 類別，這可用來代表任意一組作業為 Task<TResult>。 此作業可能為同步或非同步，而且可能為 I/O 繫結或計算繫結，或兩者兼具。
下列範例示範如何使用 TaskCompletionSource<TResult>來公開一組非同步 WebClient 作業給用戶端程式碼做為基本的 Task<TResult>。 此方法可讓您輸入 Web URL 和要搜尋的詞彙或名稱之陣列，然後傳回在每個網站出現搜尋詞彙的次數。
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 模式包裝在工作中。
請記住任何由 TaskCompletionSource<TResult> 所建立的工作，都將由 TaskCompletionSource 啟動，因此使用者程式碼不應該在該工作上呼叫 Start 方法。
使用工作來實作 APM 模式
在某些案例，可能會希望使用 API 中的 begin/end 方法組來直接公開 IAsyncResult 模式。 例如，您可能想要維護現有 API 的一致性，或者您想要有需要此模式的自動化工具。 在這種情況下，您可以使用 Task 物件來簡化內部實作 APM 模式的方式。
對於長時間執行的計算繫結方法，下列範例示範如何使用工作來實作 APM begin/end 方法組。
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 implementation 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 calculator 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(antecedent) 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 implementation 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 calculator 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 範例程式碼
StreamExtensions.cs 檔案位於 .NET Standard 平行延伸模組額外存放庫中，包含數個將 Task 物件用於非同步檔案和網路 I/O 的參考實作。
另請參閱
意見反應
即將登場：在 2024 年，我們將逐步淘汰 GitHub 問題作為內容的意見反應機制，並將它取代為新的意見反應系統。 如需詳細資訊，請參閱：https://aka.ms/ContentUserFeedback。
提交並檢視相關的意見反應