IAsyncActionWithProgress<TProgress> Interface

Definition

Namespace:

Windows.Foundation

Represents an asynchronous action that can report progress updates to callers. This is the return type for all Windows Runtime asynchronous methods that don't have a result object, but do report progress to callback listeners.

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

Type Parameters

TProgress

Attributes

ContractVersionAttribute GuidAttribute

Implements

IAsyncInfo

Windows requirements

Device family	Windows 10 (introduced in 10.0.10240.0)
API contract	Windows.Foundation.FoundationContract (introduced in v1.0)

Examples

For example C++/WinRT code illustrating how to handle the Progress event, see Delegate types for asynchronous actions and operations.

Remarks

IAsyncActionWithProgress<TProgress> is the return type for all Windows Runtime asynchronous methods that don't communicate a result object, but do enable an app to check the progress of the action. There aren't nearly as many of these as there are methods that use IAsyncAction. IAsyncAction APIs don't report progress and don't have a result.

When you use methods that return IAsyncActionWithProgress<TProgress> in your app code, you usually don't access the IAsyncAction return value directly. That's because you almost always use the language-specific awaitable syntax. In this case, the apparent return value of the method is void. For more info, see Asynchronous programming, or one of the language-specific guides to Windows Runtime asynchronous programming (Call asynchronous APIs in C# or Visual Basic, C++, JavaScript).

It's not common to use IAsyncActionWithProgress<TProgress> directly even if you don't use a language-specific awaitable syntax. Each of the languages has extension points that are generally easier to use than the Windows Runtime interface. JavaScript has WinJS.Promise, and the then/done with onProgress syntax. .NET has the AsTask extension methods, and once the IAsyncActionWithProgress<TProgress> is converted to a Task, it's easier to cancel, get notification on completion, use IProgress<T>, and so on. For C++/CX, you can wrap the calls using the Concurrency runtime (and use create_task). In other words, IAsyncActionWithProgress<TProgress> can be considered runtime-level infrastructure, which each of the languages use as a framework to support awaitable syntax or asynchronous programming models in their own way.

Specifically, if you want to handle progress in .NET code, use the AsTask signature that in an extension usage has a single IProgress reference parameter. (In this usage, the progress unit is already constrained and matches the IAsyncActionWithProgress method you're using.) Provide an object that implements IProgress, and your Report method implementation is invoked each time the Windows Runtime method reports a progress notification.

To monitor the progress of the action (if not using the language-specific techniques described above), set the Progress property, providing it the name of a method that implements the AsyncActionProgressHandler<TProgress> delegate.

C++/WinRT extension functions

Note

Extension functions exist on the C++/WinRT projection types for certain Windows Runtime APIs. For example, winrt::Windows::Foundation::IAsyncAction is the C++/WinRT projection type for IAsyncAction. The extension functions aren't part of the application binary interface (ABI) surface of the actual Windows Runtime types, so they're not listed as members of the Windows Runtime APIs. But you can call them from within any C++/WinRT project. See C++/WinRT functions that extend Windows Runtime APIs.

void get() const;

Waits synchronously for the action to complete. Throws a corresponding exception if the action is canceled, or enters an error state. You mustn't call it from a single-threaded apartment. For more info, and code examples showing how to call get, see Write a coroutine.

AsyncStatus wait_for(TimeSpan const& timeout) const;

Waits synchronously for the action to complete, or for the specified timeout. Returns the state of the IAsyncActionWithProgress, or AsyncStatus::Started if the timeout elapsed. If the action didn't time out, then call GetResults to obtain the results of the action. For more info, and code examples showing how to call wait_for, see Asynchronous timeouts made easy.

Interface inheritance

IAsyncActionWithProgress<TProgress> inherits IAsyncInfo.Types that implement IAsyncActionWithProgress<TProgress> also implement the interface members of IAsyncInfo:

• Cancel method
• Close method
• ErrorCode property
• Id property
• Status property

Notes to implementers

As with calling the existing methods, there are language-specific ways to define asynchronous methods that don't use IAsyncActionWithProgress<TProgress> directly. If writing code using .NET, your method can return a Task. For C++/CX, you can use the Concurrency runtime. However, if you're defining a component, you can use Task/task internally but you must return one of the Windows Runtime interfaces for your public methods. The language-specific asynchronous support types (and many other language-specific types you might conventionally use in code) can't be used for the public surface area of a Windows Runtime component.

Properties

Completed	Gets or sets the delegate that is called when the action completes.
ErrorCode	Gets a string that describes an error condition of the asynchronous operation. (Inherited from IAsyncInfo)
Id	Gets the handle of the asynchronous operation. (Inherited from IAsyncInfo)
Progress	Gets or sets the callback method that receives progress notification.
Status	Gets a value that indicates the status of the asynchronous operation. (Inherited from IAsyncInfo)

Methods

Cancel()	Cancels the asynchronous operation. (Inherited from IAsyncInfo)
Close()	Closes the asynchronous operation. (Inherited from IAsyncInfo)
GetResults()	Returns the results of the action.

See also

• IAsyncInfo
• IAsyncAction