IAsyncOperationWithProgress<TResult,TProgress> 介面
定義
重要
部分資訊涉及發行前產品，在發行之前可能會有大幅修改。 Microsoft 對此處提供的資訊，不做任何明確或隱含的瑕疵擔保。
表示可以向呼叫端報告進度更新的異步操作。 這是許多 Windows 執行階段 異步方法的傳回類型，這些方法具有結果，也會報告進度。
public interface class IAsyncOperationWithProgress : IAsyncInfo/// [Windows.Foundation.Metadata.ContractVersion(Windows.Foundation.FoundationContract, 65536)]
/// [Windows.Foundation.Metadata.Guid(3050321623, 58007, 18831, 186, 96, 2, 137, 231, 110, 35, 221)]
template <typename TResult, typename TProgress>
struct IAsyncOperationWithProgress : IAsyncInfo[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.Foundation.FoundationContract), 65536)]
[Windows.Foundation.Metadata.Guid(3050321623, 58007, 18831, 186, 96, 2, 137, 231, 110, 35, 221)]
public interface IAsyncOperationWithProgress<TResult,TProgress> : IAsyncInfoPublic Interface IAsyncOperationWithProgress(Of TResult, TProgress)
Implements IAsyncInfo類型參數
- TResult
- TProgress
- 衍生
- 屬性
- 實作
Windows 需求
| 裝置系列 |
Windows 10 (已於 10.0.10240.0 引進)
|
| API contract |
Windows.Foundation.FoundationContract (已於 v1.0 引進)
|
備註
IAsyncOperationWithProgress TResult，TProgress<> 是完成時產生結果之許多 Windows 執行階段 異步方法的傳回類型，也支援報告進度 (哪些呼叫端可以訂閱的通知，方法是指派 Progress) 的回呼。 這構成大約 100 個不同的 Windows 執行階段 API。 未報告進度 (但有結果的 API) 使用另一個介面 IAsyncOperation<TResult>。
當您在應用程式程序代碼中使用傳回 IAsyncOperationWithProgress<TResult，TProgress> (與 TResult 特定條件約束的方法) 時，您通常不會直接存取 IAsyncOperationWithProgress 傳回值。 這是因為您幾乎一律使用特定語言的可等候語法。 在此情況下，方法的明顯傳回值是提供做為 TResult 參數的類型。 如需詳細資訊，請參閱異步程序設計或其中一個特定語言指南，以 Windows 執行階段 異步程序設計 (在 C# 或 Visual Basic、C++、JavaScript) 中呼叫異步 API。
即使您未使用特定語言的可等候語法，也不會直接使用 IAsyncOperationWithProgress<TResult，TProgress> 。 每個語言都有擴充點，通常比 Windows 執行階段 介面更容易使用。 JavaScript 具有 WinJS.Promise，以及 then/done 語法。 .NET 具有 AsTask 擴充方法，一旦 IAsyncOperationWithProgress TResult，TProgress<> 轉換成 Task<TResult>，比較容易取得結果、取消、完成通知等等。 針對 C++/CX，您可以使用 並行運行 時間 (包裝呼叫，並使用 create_task) 。 換句話說，IAsyncOperationWithProgress TResult，TProgress<> 可以視為運行時間層級基礎結構，每個語言都會使用它們作為架構，以支援可等候的語法或異步程序設計模型。
具體而言，如果您想要處理 .NET 程式代碼中的進度，請使用擴充功能使用方式中有單一 IProgress 參考參數的 AsTask 簽章。 (在此用法中，進度單位已經受到限制，且符合您正在使用的IAsyncOperationWithProgress方法。) 提供實作 IProgress 的物件，而且每次 Windows 執行階段 方法報告進度通知時，都會叫用您的 Report 方法實作。
若要監視動作的進度， (如果未使用上述語言特定技術) ，請設定 Progress 屬性，並提供實作 AsyncOperationProgressHandler<TResult，TProgress> 委派的方法名稱。
C++/WinRT 延伸模組函式
注意
擴充功能函式存在於特定 Windows 執行階段 API 的 C++/WinRT 投影類型上。 例如， winrt：：Windows：：Foundation：：IAsyncAction 是 IAsyncAction 的 C++/WinRT 投影類型。 延伸模組函式不是應用程式二進位介面的一部分， (ABI) 實際 Windows 執行階段 型別的介面，因此它們不會列為 Windows 執行階段 API 的成員。 但您可以從任何 C++/WinRT 專案內呼叫它們。 請參閱擴充 Windows 執行階段 API 的 C++/WinRT 函式。
TResult get() const;
以同步方式等候作業完成，並傳回已完成的值。 如果作業已取消，或進入錯誤狀態，則會擲回對應的例外狀況。 您不得從單個線程 Apartment 呼叫它。 如需詳細資訊，以及示範如何呼叫 get 的程式代碼範例，請參閱 撰寫協同程式。
AsyncStatus wait_for(TimeSpan const& timeout) const;
以同步方式等候作業完成，或等候指定的逾時。 傳回 IAsyncOperationWithProgress 的狀態，如果逾時經過，則傳回 AsyncStatus：：Started 。 如果動作沒有逾時，請呼叫 GetResults 以取得作業的結果。 如需詳細資訊，以及顯示如何呼叫 wait_for的程式代碼範例，請參閱 讓異步逾時變得容易。
介面繼承
IAsyncOperationWithProgress<TResult，TProgress> 繼承 IAsyncInfo。 實作 IAsyncOperationWithProgress TResult，TProgress<> 的類型也會實作 IAsyncInfo 的介面成員：
實作者的注意事項
如同呼叫現有的方法，有一些特定語言的方式來定義不使用 IAsyncOperationWithProgress TResult，TProgress<> 的異步方法。 如果使用 .NET 撰寫程序代碼，您的方法可以傳回 Task<TResult>。 針對 C++/CX，您可以使用 並行運行時間。 不過，如果您要定義元件，您可以在內部使用Task工作/，但您必須傳回公用方法的其中一個 Windows 執行階段介面。 語言特定的異步支援類型 (，以及您可能在程式代碼中使用的許多其他語言特定類型，) 無法用於 Windows 執行階段元件的公用介面區。
屬性
| Completed |
取得或設定作業完成時所呼叫的委派。 |
| ErrorCode |
取得字串，描述異步操作的錯誤狀況。 (繼承來源 IAsyncInfo) |
| Id |
取得異步操作的句柄。 (繼承來源 IAsyncInfo) |
| Progress |
取得或設定處理進度通知的方法。 |
| Status |
取得值，這個值表示異步操作的狀態。 (繼承來源 IAsyncInfo) |
方法
| Cancel() |
取消異步操作。 (繼承來源 IAsyncInfo) |
| Close() |
關閉異步操作。 (繼承來源 IAsyncInfo) |
| GetResults() |
傳回作業的結果。 |