IAsyncActionWithProgress<TProgress> 介面

定義

表示非同步動作,可向呼叫端報告進度更新。 這是所有沒有結果物件的非同步方法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
屬性
實作

Windows 需求

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

範例

如需 C++/WinRT 程式碼說明如何處理 Progress 事件,請參閱 委派非同步動作和作業的類型

備註

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

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

即使您未使用特定語言的可等候語法,也不會直接使用 IAsyncActionWithProgress TProgress <> 。 每個語言都有擴充點,通常比Windows 執行階段介面更容易使用。 JavaScript 具有WinJS.Promise,然後使用onProgress語法完成的 。 .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的介面成員:

實作者的注意事項

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

屬性

Completed

取得或設定處理動作完成通知的方法。

ErrorCode

取得描述非同步作業錯誤條件的字串。

(繼承來源 IAsyncInfo)
Id

取得非同步作業的控制碼。

(繼承來源 IAsyncInfo)
Progress

取得或設定接收進度通知的回呼方法。

Status

取得值,這個值表示非同步作業的狀態。

(繼承來源 IAsyncInfo)

方法

Cancel()

取消非同步作業。

(繼承來源 IAsyncInfo)
Close()

關閉非同步作業。

(繼承來源 IAsyncInfo)
GetResults()

傳回動作的結果。

適用於

另請參閱