非同步程式設計模型 (APM)Asynchronous Programming Model (APM)

使用 IAsyncResult 設計模式的非同步作業會實作為兩種方法,一種名為 BeginOperationName,另一種名為 EndOperationName,這兩種方法分別負責開始和結束非同步作業 OperationNameAn asynchronous operation that uses the IAsyncResult design pattern is implemented as two methods named BeginOperationName and EndOperationName that begin and end the asynchronous operation OperationName respectively. 例如, FileStream 類別提供 BeginReadEndRead 方法,以非同步方式讀取檔案的位元組。For example, the FileStream class provides the BeginRead and EndRead methods to asynchronously read bytes from a file. 這些方法實作 Read 方法的非同步版本。These methods implement the asynchronous version of the Read method.

注意

從 .NET Framework 4 開始,工作平行程式庫會為非同步處理和平行程式設計提供新的模型。Starting with the .NET Framework 4, the Task Parallel Library provides a new model for asynchronous and parallel programming. 如需詳細資訊,請參閱 Task Parallel Library (TPL)Task-based Asynchronous Pattern (TAP)For more information, see Task Parallel Library (TPL) and Task-based Asynchronous Pattern (TAP)).

呼叫 BeginOperationName 之後,應用程式可以繼續對進行呼叫的執行緒執行指令,而非同步作業會在不同的執行緒上執行。After calling BeginOperationName, an application can continue executing instructions on the calling thread while the asynchronous operation takes place on a different thread. 每次呼叫 BeginOperationName 後,應用程式也要呼叫 EndOperationName 才能取得作業的結果。For each call to BeginOperationName, the application should also call EndOperationName to get the results of the operation.

開始非同步作業Beginning an Asynchronous Operation

BeginOperationName 方法開始非同步作業 OperationName,並傳回實作 IAsyncResult 介面的物件。The BeginOperationName method begins asynchronous operation OperationName and returns an object that implements the IAsyncResult interface. IAsyncResult 物件會儲存非同步作業的相關資訊。IAsyncResult objects store information about an asynchronous operation. 下表顯示非同步作業的相關資訊。The following table shows information about an asynchronous operation.

成員Member 說明Description
AsyncState 選擇性的應用程式特定物件,其中包含非同步作業的相關資訊。An optional application-specific object that contains information about the asynchronous operation.
AsyncWaitHandle WaitHandle 可用來封鎖應用程式執行,直到非同步作業完成。A WaitHandle that can be used to block application execution until the asynchronous operation completes.
CompletedSynchronously 這個值指出,非同步作業是否是在用來呼叫 BeginOperationName 的執行緒上完成的,而不是在個別 ThreadPool 執行緒上完成。A value that indicates whether the asynchronous operation completed on the thread used to call BeginOperationName instead of completing on a separate ThreadPool thread.
IsCompleted 指出非同步作業是否完成的值。A value that indicates whether the asynchronous operation has completed.

BeginOperationName 方法會使用任何方法同步版本簽章中所宣告,以傳值或傳址方式傳遞的參數。A BeginOperationName method takes any parameters declared in the signature of the synchronous version of the method that are passed by value or by reference. 任何 out 參數都不是 BeginOperationName 方法簽章的一部分。Any out parameters are not part of the BeginOperationName method signature. BeginOperationName 方法簽章還包括另外兩個參數。The BeginOperationName method signature also includes two additional parameters. 它們之中的第一個定義 AsyncCallback 委派,參考非同步作業完成時呼叫的方法。The first of these defines an AsyncCallback delegate that references a method that is called when the asynchronous operation completes. 如果不想在作業完成時叫用方法,呼叫端可以指定 null (在 Visual Basic 中為Nothing )。The caller can specify null (Nothing in Visual Basic) if it does not want a method invoked when the operation completes. 第二個參數是使用者定義的物件。The second additional parameter is a user-defined object. 這個物件可以用來將應用程式專屬的狀態資訊傳遞至非同步作業完成時叫用的方法。This object can be used to pass application-specific state information to the method invoked when the asynchronous operation completes. 如果 BeginOperationName 方法使用其他作業特定參數 (例如用來儲存從檔案讀取位元組的位元組陣列),AsyncCallback 和應用程式狀態物件就會是 BeginOperationName 方法簽章中最後的參數。If a BeginOperationName method takes additional operation-specific parameters, such as a byte array to store bytes read from a file, the AsyncCallback and application state object are the last parameters in the BeginOperationName method signature.

BeginOperationName 會立即將控制權傳回呼叫的執行緒。BeginOperationName returns control to the calling thread immediately. 如果 BeginOperationName 方法擲回例外狀況,則例外狀況會在非同步作業啟動之前擲回。If the BeginOperationName method throws exceptions, the exceptions are thrown before the asynchronous operation is started. 如果 BeginOperationName 方法擲回例外狀況,則不會叫用回呼方法。If the BeginOperationName method throws exceptions, the callback method is not invoked.

結束非同步作業Ending an Asynchronous Operation

EndOperationName 方法會結束非同步作業 OperationNameThe EndOperationName method ends asynchronous operation OperationName. EndOperationName 方法的傳回值型別與其同步版本所傳回的型別相同,而且是非同步作業專屬。The return value of the EndOperationName method is the same type returned by its synchronous counterpart and is specific to the asynchronous operation. 例如, EndRead 方法會傳回從 FileStream 讀取的位元組數目,而 EndGetHostByName 方法會傳回包含主機電腦相關資訊的 IPHostEntry 物件。For example, the EndRead method returns the number of bytes read from a FileStream and the EndGetHostByName method returns an IPHostEntry object that contains information about a host computer. EndOperationName 方法會使用在此方法同步版本簽章中所宣告的任何 out 或 ref 參數。The EndOperationName method takes any out or ref parameters declared in the signature of the synchronous version of the method. 除了同步方法中的參數外,EndOperationName 方法還包括 IAsyncResult 參數。In addition to the parameters from the synchronous method, the EndOperationName method also includes an IAsyncResult parameter. 呼叫者必須傳遞 BeginOperationName 的對應呼叫所傳回的執行個體。Callers must pass the instance returned by the corresponding call to BeginOperationName.

如果呼叫 EndOperationName 時,IAsyncResult 物件所代表的非同步作業還沒有完成,EndOperationName 就會封鎖呼叫執行緒,直到非同步作業完成為止。If the asynchronous operation represented by the IAsyncResult object has not completed when EndOperationName is called, EndOperationName blocks the calling thread until the asynchronous operation is complete. 非同步作業所擲回的例外狀況都是從 EndOperationName 方法擲回。Exceptions thrown by the asynchronous operation are thrown from the EndOperationName method. 使用相同的 EndOperationName 多次呼叫 IAsyncResult 方法的效果尚未定義。The effect of calling the EndOperationName method multiple times with the same IAsyncResult is not defined. 使用並非由相關 Begin 方法所傳回的 IAsyncResult 呼叫 EndOperationName 方法的方式,也同樣尚未定義。Likewise, calling the EndOperationName method with an IAsyncResult that was not returned by the related Begin method is also not defined.

注意

對任一未定義的情況,實施者應該考慮擲回 InvalidOperationExceptionFor either of the undefined scenarios, implementers should consider throwing InvalidOperationException.

注意

這個設計模式的實施者應該告知呼叫端,非同步作業已透過將 IsCompleted 設定為 true、呼叫非同步回呼方法 (如果有指定) 和傳送訊號給 AsyncWaitHandle而完成。Implementers of this design pattern should notify the caller that the asynchronous operation completed by setting IsCompleted to true, calling the asynchronous callback method (if one was specified) and signaling the AsyncWaitHandle.

應用程式開發人員有數項設計選擇,可存取非同步作業的結果。Application developers have several design choices for accessing the results of the asynchronous operation. 正確的選擇取決於當作業完成時,應用程式是否有可以執行的指示。The correct choice depends on whether the application has instructions that can execute while the operation completes. 如果應用程式一直到接收到非同步作業的結果,都無法執行任何額外的工作,它就必須封鎖直到取得結果為止。If an application cannot perform any additional work until it receives the results of the asynchronous operation, the application must block until the results are available. 若要封鎖到非同步作業完成,您可以使用下列方法的其中之一:To block until an asynchronous operation completes, you can use one of the following approaches:

在非同步作業完成時不需要封鎖的應用程式,可以使用下列方法的其中之一:Applications that do not need to block while the asynchronous operation completes can use one of the following approaches:

另請參閱See also