Application.DispatcherShutdownMode Property

Definition

Namespace:

Microsoft.UI.Xaml

Gets or sets a value that specifies whether the DispatcherQueue event loop exits when all XAML windows on a thread are closed.

public:
 property DispatcherShutdownMode DispatcherShutdownMode { DispatcherShutdownMode get(); void set(DispatcherShutdownMode value); };

DispatcherShutdownMode DispatcherShutdownMode();

void DispatcherShutdownMode(DispatcherShutdownMode value);

public DispatcherShutdownMode DispatcherShutdownMode { get; set; }

var dispatcherShutdownMode = application.dispatcherShutdownMode;
application.dispatcherShutdownMode = dispatcherShutdownMode;

Public Property DispatcherShutdownMode As DispatcherShutdownMode

Property Value

DispatcherShutdownMode

An enumeration value that specifies whether the DispatcherQueue event loop exits when all XAML windows on a thread are closed. See Remarks for default behavior.

Remarks

This is a per-thread property. When you set it, the property will only change for the current thread. It is possible to have different values for this property on different threads in your application.

You can set this property at any time. The XAML runtime reads the property each time the last window on any thread is closed.

When the Application.Start method is called (as it is at startup for WinUI Desktop apps), the XAML runtime sets DispatcherShutdownMode to OnLastWindowClose for the current thread. This causes the DispatcherQueue's event loop to exit when all the XAML windows on the thread are closed.

In a WinUI Desktop app, you might want your code to keep running even after all the XAML windows on the thread have closed. To accomplish this, you can set this property to OnExplicitShutdown. Then, after all the XAML windows have closed, the thread will keep running. In this state, you can still schedule work on the DispatcherQueue, run work on other threads, and display new XAML windows.

If the application does not call Application.Start (as is typically the case for XAML Islands-based applications), this property will default to OnExplicitShutdown. In this state, the XAML runtime doesn't take any action to exit the event loop when the XAML windows are closed.

When you use OnExplicitShutdown, you'll need to exit the event loop yourself when you're ready for the event loop on that thread to exit. To properly exit the event loop, call DispatcherQueue.EnqueueEventLoopExit. Alternatively, you can call Application.Exit, which also causes the XAML runtime to call PostQuitMessage.

See also

• DispatcherQueue
• XAML Islands