IAsyncAction Interface

Definition

public interface class IAsyncAction : IAsyncInfo

/// [Windows.Foundation.Metadata.ContractVersion(Windows.Foundation.FoundationContract, 65536)]
/// [Windows.Foundation.Metadata.Guid(1516535814, 33850, 19881, 134, 91, 157, 38, 229, 223, 173, 123)]
struct IAsyncAction : IAsyncInfo

[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.Foundation.FoundationContract), 65536)]
[Windows.Foundation.Metadata.Guid(1516535814, 33850, 19881, 134, 91, 157, 38, 229, 223, 173, 123)]
public interface IAsyncAction : IAsyncInfo

Public Interface IAsyncAction
Implements IAsyncInfo

Derived

Windows.Devices.Sms.DeleteSmsMessageOperation

Windows.Devices.Sms.DeleteSmsMessagesOperation

Windows.Devices.Sms.SendSmsMessageOperation

Windows.Security.Authentication.OnlineId.SignOutUserOperation

Attributes

ContractVersionAttribute GuidAttribute

Implements

IAsyncInfo

Windows requirements

Remarks

IAsyncAction is the return type for all WinRT asynchronous methods that don't communicate a result object, or ongoing progress. This constitutes over 300 different WinRT APIs. APIs that 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 WinRT 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 CoreDispatcher.RunAsync and ThreadPool.RunAsync.

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 WinRT 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 WinRT asynchronous methods use custom action types (which might have "Operation" rather than "Action" in their name). For example, SignOutUserOperation is a WinRT type that implements IAsyncAction. The SignOutUserOperation type is then used as the custom action return type for the SignOutUserAsync method.

If you have a method that returns a .NET Task and need an IAsyncAction to pass to a WinRT API, you can use the AsAsyncAction extension method.

C++/WinRT extension functions

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 IAsyncAction, 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

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

Properties

Methods

Applies to

See also

• IAsyncInfo
• IAsyncActionWithProgress<TProgress>
• Asynchronous programming