IAsyncOperationWithProgress<TResult,TProgress> 介面

參考

定義

命名空間:: Windows.Foundation

重要

部分資訊涉及發行前產品，在發行之前可能會有大幅修改。 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> : IAsyncInfo

Public Interface IAsyncOperationWithProgress(Of TResult, TProgress)
Implements IAsyncInfo

類型參數

TResult

TProgress

衍生: Windows.Devices.Sms.GetSmsMessagesOperation

屬性: ContractVersionAttribute GuidAttribute

實作: IAsyncInfo

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 的介面成員：

Cancel 方法
Close 方法
ErrorCode 屬性
Id 屬性
Status 屬性

實作者的注意事項

如同呼叫現有的方法，有一些特定語言的方式來定義不使用 IAsyncOperationWithProgress TResult，TProgress<> 的異步方法。如果使用 .NET 撰寫程序代碼，您的方法可以傳回 Task<TResult>。針對 C++/CX，您可以使用並行運行時間。不過，如果您要定義元件，您可以在內部使用Task工作/，但您必須傳回公用方法的其中一個 Windows 執行階段介面。語言特定的異步支援類型 (，以及您可能在程式代碼中使用的許多其他語言特定類型，) 無法用於 Windows 執行階段元件的公用介面區。

屬性

Completed	取得或設定作業完成時所呼叫的委派。
ErrorCode	取得字串，描述異步操作的錯誤狀況。 (繼承來源 IAsyncInfo)
Id	取得異步操作的句柄。 (繼承來源 IAsyncInfo)
Progress	取得或設定處理進度通知的方法。
Status	取得值，這個值表示異步操作的狀態。 (繼承來源 IAsyncInfo)

方法

Cancel()	取消異步操作。 (繼承來源 IAsyncInfo)
Close()	關閉異步操作。 (繼承來源 IAsyncInfo)
GetResults()	傳回作業的結果。

適用於