Information
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

CoreDispatcher.RunAsync method

Schedules the provided callback on the UI thread from a worker thread, and returns the results asynchronously.

Syntax


public IAsyncAction RunAsync(
  CoreDispatcherPriority priority, 
  DispatchedHandler agileCallback
)

Parameters

priority

Type: CoreDispatcherPriority

Specifies the priority for event dispatch. Set this to CoreDispatcherPriority::Normal.

agileCallback

Type: DispatchedHandler

The callback on which the dispatcher returns when the event is dispatched.

Return value

Type: IAsyncAction

The object that provides handlers for the completed async event dispatch.

Remarks

If you are on a worker thread and want to schedule work on the UI thread, use CoreDispatcher::RunAsync. Always set the priority to CoreDispatcherPriority::Normal or CoreDispatcherPriority::Low, and ensure that any chained callbacks also use CoreDispatcherPriority::Normal or CoreDispatcherPriority::Low.

Note  Callbacks scheduled with CoreDispatcherPriority::Low priority are called when there are no pending input events. Use the CoreDispatcherPriority::Low priority to make your app UI more responsive. To schedule background tasks, use CoreDispatcher::RunIdleAsync.
 

To spin off a worker thread from the UI thread, do not use this method (CoreDispatcher::RunAsync). Instead, use one of the Windows::System::Threading::ThreadPool::RunAsync method overloads.

Await a UI task sent from a background thread

When you update your UI from a background thread by calling RunAsync, it schedules the work on the UI thread and returns control to the caller immediately. If you need to wait for async work to complete before returning, for example, waiting for user input in a dialog box, do not use RunAsync alone. RunAsync also does not provide a way for the task to return a result to the caller.

In this example, RunAsync returns without waiting for the user input from the dialog box. (RunAsync returns as soon as the code in the lambda expression begins executing.)


//DO NOT USE THIS CODE.

await dispatcher.RunAsync(CoreDispatcherPriority.Normal, async () =>
{
   await signInDialog.ShowAsync(); 
});
// Execution continues here before the call to ShowAsync completes.

In this case, you need to use a TaskCompletionSource in combination with RunAsync to return a Task that you can await from your background thread, thereby pausing execution until the UI task completes. We recommend that you use the RunTaskAsync extension method from our task snippet library for this. It provides a robust solution that enables code running on a background thread to await a task that must run on the UI thread. See the Await a UI task sent from a background thread page for the code and example usage.

Porting from .NET

If you are porting from .NET code and using Dispatcher.BeginInvoke and Dispatcher.Invoke methods, note that CoreDispatcher::RunAsync is asynchronous. There is no synchronous version. After you change Dispatcher.Invoke to CoreDispatcher::RunAsync, your code must support the Windows Runtimeasync pattern and use the specific lambda syntax for your chosen language.

Examples

The following examples demonstrate the use of CoreDispatcher::RunAsync to schedule work on the main UI thread using the CoreWindow's event dispatcher.


await dispatcher.RunAsync(CoreDispatcherPriority.Normal, () =>
{
   rootPage.NotifyUser("The toast encountered an error", NotifyType.ErrorMessage);
});

var ignored = dispatcher.RunAsync(CoreDispatcherPriority.Normal, () =>
{
   Scenario3OutputText.Text += outputText;
});



Requirements (Windows 10 device family)

Device family

Universal, introduced version 10.0.10240.0

API contract

Windows.Foundation.UniversalApiContract, introduced version 1.0

Namespace

Windows.UI.Core
Windows::UI::Core [C++]

Metadata

Windows.Foundation.UniversalApiContract.winmd

Requirements (Windows 8.x and Windows Phone 8.x)

Minimum supported client

Windows 8

Minimum supported server

Windows Server 2012

Minimum supported phone

Windows Phone 8

Namespace

Windows.UI.Core
Windows::UI::Core [C++]

Metadata

Windows.winmd

See also

CoreDispatcher
Asynchronous programming

 

 

Show: