DependencyObject.Dispatcher Property

Definition

Namespace:

Windows.UI.Xaml

Gets the CoreDispatcher that this object is associated with. The CoreDispatcher represents a facility that can access the DependencyObject on the UI thread even if the code is initiated by a non-UI thread.

public:
 property CoreDispatcher ^ Dispatcher { CoreDispatcher ^ get(); };

CoreDispatcher Dispatcher();

public CoreDispatcher Dispatcher { get; }

var coreDispatcher = dependencyObject.dispatcher;

Public ReadOnly Property Dispatcher As CoreDispatcher

Property Value

CoreDispatcher

The CoreDispatcher that DependencyObject object is associated with, which represents the UI thread.

Examples

This example shows a usage of Dispatcher for the implicit this of a code-behind file for a Page. This example uses a lambda expression to add the DispatchedHandler implementation. The handler itself is handling the Accelerometer.ReadingChanged event, which won't be executed on the UI thread.

private async void ReadingChanged(object sender, AccelerometerReadingChangedEventArgs e)
{
    await Dispatcher.RunAsync(CoreDispatcherPriority.Normal, () =>
    {
        AccelerometerReading reading = e.Reading;
        ScenarioOutput_X.Text = String.Format("{0,5:0.00}", reading.AccelerationX);
        ScenarioOutput_Y.Text = String.Format("{0,5:0.00}", reading.AccelerationY);
        ScenarioOutput_Z.Text = String.Format("{0,5:0.00}", reading.AccelerationZ);
    });
}

Remarks

The Dispatcher property provides the CoreDispatcher reference that can be used to marshal calls coming from non-UI threads, using RunAsync and an awaitable function. For more info on awaitable functions, see Call asynchronous APIs in C# or Visual Basic. See also "DependencyObject and threading" section of the DependencyObject reference topic.

A DependencyObject must be created on a UI thread and has affinity to the UI thread. Because it's an entry point that enables getting across threads, DependencyObject.Dispatcher is the only instance API of DependencyObject or any of its subclasses that can be accessed from a non-UI thread without throwing a cross-thread exception. All other DependencyObject APIs throw an exception if you attempt to call them from a worker thread or other non-UI thread.

Specifically, the Dispatcher property gets the CoreDispatcher that is associated with the app UI thread. Running code through the RunAsync method of the CoreDispatcher is necessary if you intend to query or change the value of any dependency property, even if that object isn't yet associated with the XAML visual tree or the visible UI (the visual root of the app window).

Window.Dispatcher also references a CoreDispatcher that is associated with the UI thread. Window.Dispatcher is basically just a wrapper around CoreWindow.Dispatcher so that a Window class has easy access to it.

Note

The connection for a Dispatcher value is not available in a design-time view. This can cause issues if you've created a custom control that uses Dispatcher values and that code is accessed by a design-time environment through code paths that a design view uses, such as constructors and Loaded handlers. If you're writing a custom control and you encounter this issue, consider introducing a guard conditional in your code such as not calling that code when DesignModeEnabled is true.