Edit

App activation for Windows App SDK desktop apps

When the system or another app starts your app, it activates it. Depending on how the app is started, the activation kind varies. This article explains how to handle different activation scenarios in a Windows App SDK desktop app.

Activation overview

The Windows App SDK provides a rich activation model through the Microsoft.Windows.AppLifecycle namespace. You use AppInstance.GetActivatedEventArgs to retrieve activation details at any point.

Common activation kinds include:

Activation kind Scenario
Launch User selects the app tile or shortcut
File User opens a file associated with the app
Protocol A URI scheme registered to the app is invoked
StartupTask The app is configured to start at user logon
PushNotification The app is activated by an AppNotification (via AppNotificationManager)

Important

Windows App SDK desktop apps use Microsoft.Windows.AppLifecycle APIs for rich activation. The Microsoft.UI.Xaml.Application.OnLaunched method is still called for XAML-based apps, but it does not provide all activation kinds. Check AppInstance.GetActivatedEventArgs() for the full activation context.

Handle launch activation

The most common activation is a standard launch. Override OnLaunched in your App.xaml.cs:

using Microsoft.UI.Xaml;

public partial class App : Application
{
    private Window? m_window;

    protected override void OnLaunched(LaunchActivatedEventArgs args)
    {
        m_window = new MainWindow();
        m_window.Activate();
    }
}

// MainWindow is the window class generated by the WinUI 3 project
// template (MainWindow.xaml / MainWindow.xaml.cs).
public partial class MainWindow : Window
{
}

Handle rich activation kinds

To respond to file, protocol, or other activation kinds, check AppInstance.GetActivatedEventArgs() early in your app startup. A typical approach is to check in OnLaunched or in your Main method:

using Microsoft.UI.Xaml;
using Microsoft.Windows.AppLifecycle;

public partial class App : Application
{
    private Window? m_window;

    protected override void OnLaunched(LaunchActivatedEventArgs args)
    {
        var activatedArgs = AppInstance.GetCurrent().GetActivatedEventArgs();

        m_window = new MainWindow();

        switch (activatedArgs.Kind)
        {
            case ExtendedActivationKind.File:
                var fileArgs = activatedArgs.Data as
                    Windows.ApplicationModel.Activation.IFileActivatedEventArgs;
                if (fileArgs != null)
                {
                    // Navigate to a page that handles the file
                    // fileArgs.Files contains the list of activated files
                }
                break;

            case ExtendedActivationKind.Protocol:
                var protocolArgs = activatedArgs.Data as
                    Windows.ApplicationModel.Activation.IProtocolActivatedEventArgs;
                if (protocolArgs != null)
                {
                    // Navigate based on the URI
                    // protocolArgs.Uri contains the activation URI
                }
                break;

            default:
                // Standard launch — navigate to home page
                break;
        }

        m_window.Activate();
    }
}

// MainWindow is the window class generated by the WinUI 3 project
// template (MainWindow.xaml / MainWindow.xaml.cs).
public partial class MainWindow : Window
{
}

Register for activation kinds

How you register for file or protocol activation depends on whether your app is packaged (MSIX) or unpackaged.

Packaged apps

Register the associations in your app manifest:

File type association (in Package.appxmanifest):

<Extensions>
  <uap:Extension Category="windows.fileTypeAssociation">
    <uap:FileTypeAssociation Name="myfiletype">
      <uap:SupportedFileTypes>
        <uap:FileType>.myext</uap:FileType>
      </uap:SupportedFileTypes>
    </uap:FileTypeAssociation>
  </uap:Extension>
</Extensions>

Protocol association:

<Extensions>
  <uap:Extension Category="windows.protocol">
    <uap:Protocol Name="myapp" />
  </uap:Extension>
</Extensions>

For startup activation, see Configure your app to start at log-in.

Unpackaged apps

Unpackaged apps (for example, a plain WPF or Win32 app using the Windows App SDK) have no manifest, so you register the same activation kinds in code at startup using the static methods on Microsoft.Windows.AppLifecycle.ActivationRegistrationManager. Registrations are per-user and persist across launches, so it's safe to call this every time your app starts.

using Microsoft.Windows.AppLifecycle;

// Register a protocol (URI scheme)
ActivationRegistrationManager.RegisterForProtocolActivation(
    "myapp",            // scheme
    string.Empty,       // logo (optional)
    "My App",           // display name
    string.Empty);      // exePath — empty registers the current executable

// Register a file type
ActivationRegistrationManager.RegisterForFileTypeActivation(
    new[] { ".myext" },                 // supported file extensions
    string.Empty,                       // logo (optional)
    "My App",                           // display name
    new[] { "open" },                   // supported verbs
    string.Empty);                      // exePath — empty registers the current executable

To remove a registration (for example, during uninstall), call the matching UnregisterForProtocolActivation or UnregisterForFileTypeActivation method.

Both packaged and unpackaged apps retrieve activation arguments the same way, using AppInstance.GetCurrent().GetActivatedEventArgs(), as shown earlier in this article. For more detail, see Rich activation with the app lifecycle API.

Handle activation in a running instance

If your app is already running when a second activation occurs, you can redirect it to the existing instance using the multi-instance APIs. See Multi-instance apps for details on registering keys and redirecting activations.

Differences from UWP activation

Feature UWP Windows App SDK (Desktop)
Activation entry point OnActivated, OnFileActivated, OnLaunched overrides AppInstance.GetActivatedEventArgs() + OnLaunched
Previous execution state LaunchActivatedEventArgs.PreviousExecutionState Not provided by system — implement your own
Prelaunch support Yes (opt-in) No
Namespace Windows.ApplicationModel.Activation Microsoft.Windows.AppLifecycle (with Windows.ApplicationModel.Activation data types)

Related content

  • Last updated on