Tag Archives: Build 16226

Configure your app to start at log-in

For a long time, desktop PC users have been able to configure Win32 apps to start at startup or user log-in. This has also been possible for Desktop Bridge apps since the Windows 10 Anniversary Update (v10.0.14393.0). We’ve now extended this feature to allow regular Universal Windows Apps to take part in this also. This is available in Insider builds from Build 16226 onwards, along with the corresponding SDK. In this post, we’ll look at the code changes you need to make in your manifest and in your App class to handle the startup scenario, and how your app can work with the user to respect their choices.

Here’s a sample app, called TestStartup – the app offers a button to request enabling the startup behavior, and reports current status. Typically, you’d put this kind of option into a settings page of some kind in your app.

The first thing to note is that you must use the windows.startupTask Extension in your app manifest under the Extensions node, which is a child of the Application node. This is documented here. The same Extension declaration is used for both Desktop Bridge and regular UWP apps – but there are some differences.

  • Desktop Bridge is only available on Desktop, so it uses a Desktop-specific XML namespace. The new UWP implementation is designed for use generally on UWP, so it uses a general UAP namespace (contract version 5) – although to be clear, it is currently still only actually available on Desktop.
  • The Desktop Bridge EntryPoint must be “Windows.FullTrustApplication,” whereas for regular UWP it is the fully-qualified namespace name of your App class.
  • Desktop Bridge apps can set the Enabled attribute to true, which means that the app will start at startup without the user having to manually enable it. Conversely, for regular UWP apps this attribute is ignored, and the feature is implicitly set to “disabled.” Instead, the user must first launch the app, and the app must request to be enabled for startup activation.
  • For Desktop Bridge apps, multiple startupTask Extensions are permitted, each one can use a different Executable. Conversely, for regular UWP apps, you would have only one Executable and one startupTask Extension.
Desktop Bridge App UWP App

xmlns:desktop="http://schemas.microsoft.com/
appx/manifest/desktop/windows10"


xmlns:uap5="http://schemas.microsoft.com/
appx/manifest/uap/windows10/5"


<desktop:Extension
  Category="windows.startupTask"
  Executable="MyDesktopBridgeApp.exe"
  EntryPoint="Windows.FullTrustApplication">
  <desktop:StartupTask
    TaskId="MyStartupId"
    Enabled="false"
    DisplayName="Lorem Ipsum" />
</desktop:Extension>


<uap5:Extension
  Category="windows.startupTask"
  Executable="TestStartup.exe"
  EntryPoint="TestStartup.App">
  <uap5:StartupTask
    TaskId="MyStartupId"
    Enabled="false"
    DisplayName="Lorem Ipsum" />
</uap5:Extension>

For both Desktop Bridge apps and regular UWP apps, the user is always in control, and can change the Enabled state of your startup app at any time via the Startup tab in Task Manager:

Also for both app types, the app must be launched at least once before the user can change the Disabled/Enabled state. This is potentially slightly confusing: if the user doesn’t launch the app and then tries to change the state to Enabled in Task Manager, this will seem to be set. However, if they then close Task Manager and re-open it, they will see that the state is still Disabled. What’s happening here is that Task Manager is correctly persisting the user’s choice of the Enabled state – but this won’t actually allow the app to be activated at startup unless and until the app is launched at least once first – hence the reason it is reported as Disabled.

In your UWP code, you can request to be enabled for startup. To do this, use the StartupTask.GetAsync method to initialize a StartupTask object (documented here) – passing in the TaskId you specified in the manifest – and then call the RequestEnableAsync method. In the test app, we’re doing this in the Click handler for the button. The return value from the request is the new (possibly unchanged) StartupTaskState.


async private void requestButton_Click(object sender, RoutedEventArgs e)
{
    StartupTask startupTask = await StartupTask.GetAsync("MyStartupId");
    switch (startupTask.State)
    {
        case StartupTaskState.Disabled:
            // Task is disabled but can be enabled.
            StartupTaskState newState = await startupTask.RequestEnableAsync();
            Debug.WriteLine("Request to enable startup, result = {0}", newState);
            break;
        case StartupTaskState.DisabledByUser:
            // Task is disabled and user must enable it manually.
            MessageDialog dialog = new MessageDialog(
                "I know you don't want this app to run " +
                "as soon as you sign in, but if you change your mind, " +
                "you can enable this in the Startup tab in Task Manager.",
                "TestStartup");
            await dialog.ShowAsync();
            break;
        case StartupTaskState.DisabledByPolicy:
            Debug.WriteLine(
                "Startup disabled by group policy, or not supported on this device");
            break;
        case StartupTaskState.Enabled:
            Debug.WriteLine("Startup is enabled.");
            break;
    }
}

Because Desktop Bridge apps have a Win32 component, they run with a lot more power than regular UWP apps generally. They can set their StartupTask(s) to be Enabled in the manifest and do not need to call the API. For regular UWP apps, the behavior is more constrained, specifically:

  • The default is Disabled, so in the normal case, the user must run the app at least once explicitly – this gives the app the opportunity to request to be enabled.
  • When the app calls RequestEnableAsync, this will show a user-prompt dialog for UWP apps (or if called from a UWP component in a Desktop Bridge app from the Windows 10 Fall Creators Update onwards).
  • StartupTask includes a Disable method. If the state is Enabled, the app can use the API to set it to Disabled. If the app then subsequently requests to enable again, this will also trigger the user prompt.
  • If the user disables (either via the user prompt, or via the Task Manager Startup tab), then the prompt is not shown again, regardless of any requests from the app. The app can of course devise its own user prompts, asking the user to make manual changes in Task Manager – but if the user has explicitly disabled your startup, you should probably respect their decision and stop pestering them. In the sample code above, the app is responding to DisabledByUser by popping its own message dialog – you can obviously do this if you want, but it should be emphasized that there’s a risk you’ll just annoy the user.
  • If the feature is disabled by local admin or group policy, then the user prompt is not shown, and startup cannot be enabled. The existing StartupTaskState enum has been extended with a new value, DisabledByPolicy. When the app sees DisabledByPolicy, it should avoid re-requesting that their task be enabled, because the request will never be approved until the policy changes.
  • Platforms other than Desktop that don’t support startup tasks also report DisabledByPolicy.

Where a request triggers a user-consent prompt (UWP apps only), the message includes the DisplayName you specified in your manifest. This prompt is not shown if the state is DisabledByUser or DisabledByPolicy.

If your app is enabled for startup activation, you should handle this case in your App class by overriding the OnActivated method. Check the IActivatedEventArgs.Kind to see if it is ActivationKind.StartupTask, and if so, case the IActivatedEventArgs to a StartupTaskActivatedEventArgs. From this, you can retrieve the TaskId, should you need it. In this test app, we’re simply passing on the ActivationKind as a string to MainPage.


protected override void OnActivated(IActivatedEventArgs args)
{
    Frame rootFrame = Window.Current.Content as Frame;
    if (rootFrame == null)
    {
        rootFrame = new Frame();
        Window.Current.Content = rootFrame;
    }

    string payload = string.Empty;
    if (args.Kind == ActivationKind.StartupTask)
    { 
        var startupArgs = args as StartupTaskActivatedEventArgs;
        payload = ActivationKind.StartupTask.ToString();
    }

    rootFrame.Navigate(typeof(MainPage), payload);
    Window.Current.Activate();
}

Then, the MainPage OnNavigatedTo override tests this incoming string and uses it to report status in the UI.


protected override void OnNavigatedTo(NavigationEventArgs e)
{
    string payload = e.Parameter as string;
    if (!string.IsNullOrEmpty(payload))
    {
        activationText.Text = payload;

        if (payload == "StartupTask")
        {
            requestButton.IsEnabled = false;
            requestResult.Text = "Enabled";
            SolidColorBrush brush = new SolidColorBrush(Colors.Gray);
            requestResult.Foreground = brush;
            requestPrompt.Foreground = brush;
        }
    }
}

Note that when your app starts at startup, it will start minimized in the taskbar. In this test app, when brought to normal window mode, the app reports the ActivationKind and StartupTaskState:

Using the windows.startupTask manifest Extension and the StartupTask.RequestEnableAsync API, your app can be configured to start at user log-in. This can be useful for apps which the user expects to use heavily, and the user has control over this – but it is still a feature that you should use carefully. You should not use the feature if you don’t reasonably expect the user to want it for your app – and you should avoid repeatedly prompting them once they’ve made their choice. The inclusion of a user-prompt puts the user firmly in control, which is an improvement over the older Win32 model.

Sample Code here.

How to Restart your App Programmatically

For some apps (especially games) it is not uncommon for the app to get into a state where it needs to restart – perhaps after a license update, after installing downloadable content, its caches have become corrupt or unwieldy, or for any other reason where the app needs to refresh state from scratch. In earlier releases, your only option would have been to prompt the user to close and relaunch, or to call CoreApplication.Exit – and both options provide sub-optimal user experience.

We have therefore introduced a new API that enables an app to request immediate termination and restart, and to pass arbitrary arguments into the fresh instance. In this post, we’ll look at how this works and how you can build it into your app. This is available now in Insider builds from Build 16226 onwards, along with the corresponding SDK.

Here’s a sample app, called TestRestart. 

The app provides a ListView of cities on the left, the currently-selected city on the right and a TextBox for providing arguments to the app when it is restarted. When the user taps the Request Restart button, the app will terminate and restart itself, passing in the supplied arguments. The new API, RequestRestartAsync, is exposed as a static method on the CoreApplication object. It takes a string parameter, which can be any string value you like – including input from the user or another external entity. If you do choose to accept input in this way, it is your responsibility to validate it correctly to make sure it conforms to whatever constraints you choose to impose. You should do this validation on input, before passing it to RequestRestartAsync. In this sample app, we’re expecting the user to type in the name of a city.


async private void DoRestartRequest()
{
    bool isValidPayload = false;
    string payload = restartArgs.Text;
    if (!string.IsNullOrEmpty(payload))
    {
        foreach (ImageViewModel imageItem in imageListView.Items)
        {
            if (imageItem.Name == payload)
            {
                isValidPayload = true;
                break;
            }
        }
    }

    if (isValidPayload)
    {
        AppRestartFailureReason result =
            await CoreApplication.RequestRestartAsync(payload);
        if (result == AppRestartFailureReason.NotInForeground ||
            result == AppRestartFailureReason.RestartPending ||
            result == AppRestartFailureReason.Other)
        {
            Debug.WriteLine("RequestRestartAsync failed: {0}", result);
        }
    }
}

To mitigate privacy concerns, an app is only permitted to restart itself if it is in the foreground at the time it makes the request. When the app restarts, it restarts with normal UI – that is, as a normal foreground window. If we were to permit a background task or minimized app to restart, the result would be unexpected to the user. This is why the API is framed as a request. If the request is denied, the app would need to handle the failure – perhaps by waiting until it is in the foreground and trying again. If you were to request a restart and then through some twist of logic managed to request it again before the system started the operation, then you’d get the RestartPending result, although this is an edge case. You’re unlikely to ever get the other result – unless something goes wrong in the platform.

Note that this is the only significant constraint, but you should use this API carefully. For example, you probably should not use it if your app was not originally launched by the user – for example, if it was launched as the result of a share or picker operation. Restarting in the middle of one of those contract operations would certainly confuse the user.

If the request is granted, the app is terminated and then restarted. There are many different ways to activate an app: in addition to a regular launch activation, apps can choose to support file activation, protocol activation, share or picker activation and so on. The list is documented here. For the restart case, the app will be activated as a regular launch – just as if the user had closed the app manually and tapped its tile to launch it again – but including the arbitrary arguments supplied earlier (if any).

In your App class, you should handle this by overriding the OnActivated method. Test the ActivationKind, and if it’s ActivationKind.Launch, then the incoming IActivatedEventArgs will be a LaunchActivatedEventArgs. From this, you can get hold of the incoming activation arguments. For a regular user-initiated launch, the Arguments will be empty, so if it’s not empty you could simply infer that this is a restart activation. You can also check the PreviousExecutionState, which for a restart operation will be set to Terminated.

Although the arguments might have originated from an untrusted source (eg, the user), you should have done the validation before requesting restart. If so, you can consider them trustworthy when you receive them in OnActivated.


protected override void OnActivated(IActivatedEventArgs args)
{
    switch (args.Kind)
    {
        case ActivationKind.Launch:
            LaunchActivatedEventArgs launchArgs = args as LaunchActivatedEventArgs;
            string argString = launchArgs.Arguments;

            Frame rootFrame = Window.Current.Content as Frame;
            if (rootFrame == null)
            {
                rootFrame = new Frame();
                Window.Current.Content = rootFrame;
            }
            rootFrame.Navigate(typeof(MainPage), argString);
            Window.Current.Activate();
            break;
    }
}

What you do with the incoming arguments is entirely up to you. In this app, we’re simply passing them on to the MainPage. In the MainPage in turn, we have an override of OnNavigatedTo which uses the string to select an item in the ListView:


protected override void OnNavigatedTo(NavigationEventArgs e)

{
    string payload = e.Parameter as string;
    if (!string.IsNullOrEmpty(payload))
    {
        foreach (ImageViewModel imageItem in imageListView.Items)
        {
            if (imageItem.Name == payload)
            {
                imageListView.SelectedItem = imageItem;
                break;
            }
        }
    }
}

As you can see, the CoreApplication.RequestRestartAsync method is a simple API. You can use it to terminate your app immediately, and have it restart as if by user action, with the additional option of passing in arbitrary arguments on activation.

Sample Code here.