IAsyncAction IAsyncAction IAsyncAction IAsyncAction Interface

Represents an asynchronous action. This is the return type for many Windows Runtime asynchronous methods that don't have a result object, and don't report ongoing progress.

Syntax

Declaration

public interface IAsyncActionpublic interface IAsyncActionPublic Interface IAsyncAction

Inheritance Hierarchy

Remarks

IAsyncAction is the return type for all Windows Runtime asynchronous methods that don't communicate a result object, or ongoing progress. This constitutes over 300 different Windows Runtime APIs. APIs that do report progress (but don't have a result) use another interface, IAsyncActionWithProgress<TProgress>.

When you use methods that return IAsyncAction 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).

IAsyncAction is also an input type for some advanced-scenario utility APIs such as RunAsync(Windows.UI.Core.CoreDispatcherPriority,Windows.UI.Core.DispatchedHandler) and RunAsync(Windows.System.Threading.WorkItemHandler,Windows.System.Threading.WorkItemPriority).

It's not common to use IAsyncAction 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 IAsyncAction is converted to a Task, it's easier to 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, IAsyncAction 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.

Instead of using IAsyncAction, some Windows Runtime asynchronous methods use custom action types (which might have "Operation" rather than "Action" in their name). For example, SignOutUserOperation is a Windows Runtime type that implements IAsyncAction. The SignOutUserOperation type is then used as the custom action return type for the SignOutUserAsync() method.

Interface inheritance

IAsyncAction inherits IAsyncInfo. Types that implement IAsyncAction 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 IAsyncInfo 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 summary

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

Methods summary

Returns the results of the action.

Properties

  • Completed
    Completed
    Completed
    Completed

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

    public AsyncActionCompletedHandler Completed { get; set; }public AsyncActionCompletedHandler Completed { get; set; }Public ReadWrite Property Completed As AsyncActionCompletedHandler

    Property Value

    Remarks

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

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

    If you're implementing IAsyncAction, 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()

    Returns the results of the action.

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

    Remarks

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

    If you want the method to return a result you probably should be using IAsyncOperation<TResult> instead. For IAsyncAction, any added logic should be in the Completed implementation, not GetResults().

Device family

Windows 10 (introduced v10.0.10240.0)

API contract

Windows.Foundation.FoundationContract (introduced v1)

Attributes

Windows.Foundation.Metadata.ContractVersionAttribute
Windows.Foundation.Metadata.GuidAttribute

Details

Assembly

Windows.Foundation.dll