I​Async​Action​With​Progress<​TProgress> I​Async​Action​With​Progress<​TProgress> I​Async​Action​With​Progress<​TProgress> Interface

Definition

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 IAsyncActionWithProgress<TProgress>public interface IAsyncActionWithProgress<TProgress>Public Interface IAsyncActionWithProgress<TProgress>
Inheritance
IAsyncActionWithProgress<TProgress>IAsyncActionWithProgress<TProgress>IAsyncActionWithProgress<TProgress>
Attributes
Windows 10 requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.FoundationContract (introduced v1)

Inherited Members

Inherited methods

Inherited properties

Remarks

IAsyncActionWithProgress; 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; 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; 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; 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; 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; delegate.

Interface inheritance

IAsyncActionWithProgress; inherits IAsyncInfo.Types that implement IAsyncActionWithProgress; also implement the interface members of IAsyncInfo:

Notes to implementers

As with calling the existing methods, there are language-specific ways to define asynchronous methods that don't use IAsyncActionWithProgress; 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 Completed Completed

Gets or sets the method that handles the action completed notification.

public : AsyncActionWithProgressCompletedHandler<TProgress> Completed { get; set; }public AsyncActionWithProgressCompletedHandler<TProgress> Completed { get; set; }Public ReadWrite Property Completed As AsyncActionWithProgressCompletedHandler<TProgress>
Attributes

Remarks

The Windows Runtime enforces that this property can only be set once on an action.

Generally, a completed IAsyncActionWithProgress; method called using language-specific awaitable syntax does nothing further than to return null when it completes.

If you're implementing IAsyncActionWithProgress;, then the set implementation of Completed should store the handler, and the surrounding logic should invoke it when Close is called. The implementation should set the asyncStatus parameter of invoked callbacks appropriately if there is a Cancel call, Status is not Completed, errors occurred, and so on.

See Also

Progress Progress Progress

Gets or sets the callback method that receives progress notification.

public : AsyncActionProgressHandler<TProgress> Progress { get; set; }public AsyncActionProgressHandler<TProgress> Progress { get; set; }Public ReadWrite Property Progress As AsyncActionProgressHandler<TProgress>
Value
AsyncActionProgressHandler<TProgress> AsyncActionProgressHandler<TProgress> AsyncActionProgressHandler<TProgress>

A reference to the callback method that handles progress notifications. Implement the AsyncActionProgressHandler(TProgress) delegate to define your callback. TProgress defines the progress unit type, which varies by method implementation.

Attributes
See Also

Methods

GetResults() GetResults() GetResults()

Returns the results of the action.

public : void GetResults()public void GetResults()Public Function GetResults() As void
Attributes

Remarks

The interface definition of this method has a void return, and void is what methods that use the default IAsyncActionWithProgress; behavior will return after completing, when a language-specific awaitable syntax is used.

If you want the method to return a result you probably should be using IAsyncOperationWithProgress; instead. For IAsyncActionWithProgress;, any added logic should be in the Completed implementation, not GetResults.

See Also

See Also