Definition

Represents an asynchronous operation that can report progress updates to callers. This is the return type for many Windows Runtime asynchronous methods that have results and also report progress.

In This Article

public : interface IAsyncOperationWithProgress<TResult, TProgress>public interface IAsyncOperationWithProgress<TResult, TProgress>Public Interface IAsyncOperationWithProgress<TResult, TProgress>// You can use this interface in JavaScript.

Inherited Members

Inherited methods

Inherited properties

Remarks

IAsyncOperationWithProgress; is the return type for many Windows Runtime asynchronous methods that have a result upon completion, and also support notifications that report progress (which callers can subscribe to by assigning a callback for Progress ). This constitutes about 100 different Windows Runtime APIs. APIs that don't report progress (but do have a result) use another interface, IAsyncOperation;.

It's not common to use IAsyncOperationWithProgress; 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 syntax. .NET has the AsTask extension method, and once the IAsyncOperationWithProgress; is converted to a Task<TResult>, it's easier to get the result, cancel, get notification on completion, and so on. For C++/CX, you can wrap the calls using the Concurrency runtime (and use create_task). In other words, IAsyncOperationWithProgress; 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 IAsyncOperationWithProgress 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 AsyncOperationProgressHandler; delegate.

Notes to implementers

As with calling the existing methods, there are language-specific ways to define asynchronous methods that don't use IAsyncOperationWithProgress; directly. If writing code using .NET, your method can return a Task<TResult>. 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.

Remarks

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

Generally, a completed AsyncOperationWithProgressCompletedHandler, TProgress> method called using awaitable syntax does nothing further than to return its result (an object of the TResult type) when it completes.

If you're implementing AsyncOperationWithProgressCompletedHandler, TProgress>, 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.

Methods

GetResults()GetResults()GetResults()GetResults()

public : TResult GetResults()public TResult GetResults()Public Function GetResults() As TResult// You can use this method in JavaScript.

Returns

TResultTResultTResultTResult

The results of the operation.

Remarks

Notes to implementers

Implementers should return the specific value that the operation type should return to callers upon completion. When the method that uses the custom operation type returns, while using an awaitable syntax (the usual usage) this provides the return value of the operation to the method caller.