IAsyncActionWithProgress<TProgress> 介面

定義

命名空間:

Windows.Foundation

表示可以向呼叫端報告進度更新的異步動作。 這是所有沒有結果物件的 Windows 執行階段 異步方法的傳回類型，但會向回呼接聽程式回報進度。

public interface class IAsyncActionWithProgress : IAsyncInfo

/// [Windows.Foundation.Metadata.ContractVersion(Windows.Foundation.FoundationContract, 65536)]
/// [Windows.Foundation.Metadata.Guid(527282776, 59395, 18593, 149, 70, 235, 115, 83, 57, 136, 132)]
template <typename TProgress>
struct IAsyncActionWithProgress : IAsyncInfo

[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.Foundation.FoundationContract), 65536)]
[Windows.Foundation.Metadata.Guid(527282776, 59395, 18593, 149, 70, 235, 115, 83, 57, 136, 132)]
public interface IAsyncActionWithProgress<TProgress> : IAsyncInfo

Public Interface IAsyncActionWithProgress(Of TProgress)
Implements IAsyncInfo

類型參數

TProgress

屬性

ContractVersionAttribute GuidAttribute

實作

IAsyncInfo

Windows 需求

裝置系列	Windows 10 (已於 10.0.10240.0 引進)
API contract	Windows.Foundation.FoundationContract (已於 v1.0 引進)

範例

如需說明如何處理 Progress 事件的 C++/WinRT 程式代碼範例，請參閱異步動作和作業的委派類型。

備註

IAsyncActionWithProgress TProgress<> 是未傳達結果物件之所有 Windows 執行階段 異步方法的傳回類型，但請讓應用程式檢查動作的進度。 使用 IAsyncAction 的方法不一樣多。 IAsyncAction API 不會報告進度，也不會有結果。

當您在應用程式程序代碼中使用傳回 IAsyncActionWithProgress TProgress<> 的方法時，您通常不會直接存取 IAsyncAction 傳回值。 這是因為您幾乎一律使用特定語言的可等候語法。 在此情況下，方法的明顯傳回值為 void。 如需詳細資訊，請參閱異步程序設計，或 Windows 執行階段 異步程序設計 (在 C# 或 Visual Basic、C++、JavaScript) 中呼叫異步 API 的其中一個語言特定指南。

即使您未使用特定語言的可等候語法，也不會直接使用 IAsyncActionWithProgress TProgress<>。 每個語言都有擴充點，通常比 Windows 執行階段 介面更容易使用。 JavaScript 具有 WinJS.Promise，且具有 onProgress 語法的 then/done。 .NET 具有 AsTask 擴充方法，一旦 IAsyncActionWithProgress TProgress<> 轉換成 Task，就更容易取消、完成時收到通知、使用 IProgress<T> 等等。 針對 C++/CX，您可以使用 並行運行 時間 (包裝呼叫，並使用 create_task) 。 換句話說，IAsyncActionWithProgress TProgress<> 可以視為運行時間層級基礎結構，每個語言都會用做為架構，以自己的方式支援可等候的語法或異步程序設計模型。

具體而言，如果您想要處理 .NET 程式代碼中的進度，請使用擴充功能使用方式中有單一 IProgress 參考參數的 AsTask 簽章。 (在此用法中，進度單位已受到限制，且符合您正在使用的IAsyncActionWithProgress方法。) 提供實作 IProgress 的物件，而且每次 Windows 執行階段 方法報告進度通知時，都會叫用 Report 方法實作。

若要監視動作的進度， (如果未使用上述語言特定技術) ，請設定 Progress 屬性，並提供實作 AsyncActionProgressHandler<TProgress> 委派的方法名稱。

C++/WinRT 延伸模組函式

注意

擴充功能函式存在於特定 Windows 執行階段 API 的 C++/WinRT 投影類型上。 例如， winrt：：Windows：：Foundation：：IAsyncAction 是 IAsyncAction 的 C++/WinRT 投影類型。 擴充函式不是應用程式二進位介面的一部分， (實際 Windows 執行階段 類型的 ABI) 介面，因此它們不會列為 Windows 執行階段 API 的成員。 但您可以從任何 C++/WinRT 專案內呼叫它們。 請參閱擴充 Windows 執行階段 API 的 C++/WinRT 函式。

void get() const;

以同步方式等候動作完成。 如果動作已取消，或進入錯誤狀態，則會擲回對應的例外狀況。 您不得從單個線程 Apartment 呼叫它。 如需詳細資訊，以及示範如何呼叫 get 的程式代碼範例，請參閱 撰寫協同程式。

AsyncStatus wait_for(TimeSpan const& timeout) const;

以同步方式等候動作完成，或等候指定的逾時。 會傳回 IAsyncActionWithProgress 的狀態，如果逾時經過，則傳回 AsyncStatus：：Started 。 如果動作沒有逾時，請呼叫 GetResults 以取得動作的結果。 如需詳細資訊，以及顯示如何呼叫 wait_for的程式代碼範例，請參閱 讓異步逾時變得容易。

介面繼承

IAsyncActionWithProgress TProgress<> 繼承 IAsyncInfo。實作 IAsyncActionWithProgress TProgress<> 的類型也會實作 IAsyncInfo 的介面成員：

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

實作者的注意事項

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

屬性

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

方法

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

另請參閱

• IAsyncInfo
• IAsyncAction