Command-Line Activation of Universal Windows Apps

As we continue to close the gap between Win32 and Universal Windows Apps, one of the features we’ve recently introduced is the ability to activate a UWA from a command line and pass the app arbitrary command-line arguments. This is available to Insiders from build 16226.

This feature builds on the App Execution Alias extension already available for Desktop Bridge apps. To use this feature in a UWA, there are two key additions to your app:

  • Add an appExecutionAlias extension to your app manifest.
  • Override OnActivated and handle the incoming arguments.

For the manifest entry, you first need to declare the XML namespace for the AppExecutionAlias element:


<Package
  xmlns="http://schemas.microsoft.com/appx/manifest/foundation/windows10"
  xmlns:mp="http://schemas.microsoft.com/appx/2014/phone/manifest"
  xmlns:uap="http://schemas.microsoft.com/appx/manifest/uap/windows10"
  xmlns:uap5="http://schemas.microsoft.com/appx/manifest/uap/windows10/5" 
  IgnorableNamespaces="uap mp uap5">

The AppExecutionAlias is declared as an Extension within your Application. This is quite simple and almost the same as for a Desktop Bridge app:


<Application ...>
      
  <Extensions>
      <uap5:Extension 
        Category="windows.appExecutionAlias" 
        Executable="MyCompany.Something.Another.exe" 
        EntryPoint=" MyCompany.Something.Another.App">
        <uap5:AppExecutionAlias>
          <uap5:ExecutionAlias Alias="MyApp.exe" />
        </uap5:AppExecutionAlias>
      </uap5:Extension>
  </Extensions>

</Application>

The Executable is the name of your UWA app EXE, and the EntryPoint is the fully qualified name of your App class. The ExecutionAlias is the name that users will type in at the command-line: This can be any arbitrary name, and it must end with “.exe.” You should choose a meaningful alias that you can reasonably expect the user to associate with your app. Note that if you choose an alias that conflicts with an app that is already installed, your alias won’t be used. Similarly, if your app is installed first, and then the user installs another app later that declares the same alias – then your app will take precedence. The rule here is that the first one wins.

The manifest entry is obviously the same for VB and C++ projects, but for a JavaScript web app, it’s slightly different. Instead of Executable, you specify a StartPage, and you don’t specify EntryPoint at all:


<Extensions>
    <uap5:Extension 
      Category="windows.appExecutionAlias" 
      StartPage="index.html">
      <uap5:AppExecutionAlias>
        <uap5:ExecutionAlias Alias="MyApp.exe" />
      </uap5:AppExecutionAlias>
    </uap5:Extension>
</Extensions>

For the OnActivated override, the first thing to do is to check the ActivationKind – this is standard practice if your app supports multiple activation kinds (file associations, custom protocols and so on). In this scenario, if the ActivationKind is CommandLineLaunch, the incoming IActivatedEventArgs will be an object of type CommandLineActivatedEventArgs. From this, you can get the CommandLineActivationOperation, and from this in turn, you can get the Arguments string. You also get the CurrentDirectoryPath, which is the directory current when the command-line activation request was made. This is typically not the install location of the app itself, but could be any arbitrary path.


async protected override void OnActivated(IActivatedEventArgs args)
{
    switch (args.Kind)
    {
        case ActivationKind.CommandLineLaunch:
            CommandLineActivatedEventArgs cmdLineArgs = 
                args as CommandLineActivatedEventArgs;
            CommandLineActivationOperation operation = cmdLineArgs.Operation;
            string cmdLineString = operation.Arguments;
            string activationPath = operation.CurrentDirectoryPath;

It’s important to remember that the command-line arguments are supplied by the caller, which means that you have no control over them. You should treat these arguments as untrustworthy and parse them very carefully. They might not have any malicious intent, but they could easily be badly formed, so you need to allow for this.

After the initial checks, you can create a window as normal, and optionally pass in the (parsed and validated) command-line arguments – or some data extracted from the arguments – to that window.


            Frame rootFrame = Window.Current.Content as Frame;
            if (rootFrame == null)
            {
                rootFrame = new Frame();
                Window.Current.Content = rootFrame;
            }
            rootFrame.Navigate(typeof(MainPage), 
                string.Format("CurrentDirectory={0}, Arguments={1}",
                activationPath, cmdLineString));
            Window.Current.Activate();

Finally, in your page’s OnNavigatedTo, you can retrieve the payload from the event args, and use the information in any way you like:


protected override void OnNavigatedTo(NavigationEventArgs e)
{
    string cmdLineString = e.Parameter as string;
}

When you build and run the app on your dev machine – or when the end user installs your app – the  alias is registered. From that point, the user can go to a command line and activate your app.

Note that by “command line,” we mean any common command line mechanism such as cmd.exe,  powershell.exe, Windows-R and so on. Here’s a slightly more sophisticated example in which the app implements a custom parser to construct command-payload tuples from the command-line arguments:


protected override void OnActivated(IActivatedEventArgs args)
{
    switch (args.Kind)
    {
        case ActivationKind.CommandLineLaunch:
            CommandLineActivatedEventArgs cmdLineArgs = 
                args as CommandLineActivatedEventArgs;
            CommandLineActivationOperation operation = cmdLineArgs.Operation;
            string cmdLineString = operation.Arguments;
            string activationPath = operation.CurrentDirectoryPath;

            Frame rootFrame = Window.Current.Content as Frame;
            if (rootFrame == null)
            {
                rootFrame = new Frame();
                Window.Current.Content = rootFrame;
            }

            ParsedCommands parsedCommands = 
                CommandLineParser.ParseUntrustedArgs(cmdLineString);
            if (parsedCommands != null && parsedCommands.Count > 0)
            {
                foreach (ParsedCommand command in parsedCommands)
                {
                    switch (command.Type)
                    {
                        case ParsedCommandType.SelectItem:
                            rootFrame.Navigate(typeof(SelectItemPage), command.Payload);
                            break;
                        case ParsedCommandType.LoadConfig:
                            rootFrame.Navigate(typeof(LoadConfigPage), command.Payload);
                            break;
                        case ParsedCommandType.Unknown:
                            rootFrame.Navigate(typeof(HelpPage), cmdLineString);
                            break;
                    }
                }
            }
            else
            {
                rootFrame.Navigate(typeof(MainPage));
            }

            Window.Current.Activate();
            break;
    }
}

The app’s logic uses these more structured commands to navigate to different pages and handle the payload in different ways. The point is that you can define whatever argument options and payload rules you like in your app.

A common scenario is testing: You can activate your app with a defined set of values for each test run – for example, to start on a particular page with boundary values set for key items – or to start a game at a particular level, with values set for player attributes, enemy count, damage levels, fuel and weaponry and so on.

If the data you provide is too long or too complex for command-line arguments, you can supply a filename on the command-line which the app can then load. One option is to include such files as content in your package (and most likely strip them out before building your release build). You can also create the files at any time later, so long as you put them in a location to which the app has access. If you want to avoid showing any filepicker UX in your app, the simplest option is to put the files in the install location for the app, which would be somewhere like %userprofile%AppDataLocalPackages<Package ID>LocalState.

You should also allow for incoming arguments that are badly formed or otherwise unrecognized:

And a reasonable UX here would be to navigate to a page where you show the user the correct usage options:

Also, bear in mind that the UWP platform has a single-instance app model. This means that your app can be running, and you can then continue to execute command-line activation requests at any point thereafter. Each activation will result in a call into OnActivated. This is unlikely to be useful in end-user scenarios of course – but it can be a useful debugging/profiling strategy during development.

Command-line activation of UWAs is just one example of how we’re gradually closing the gaps between traditional Win32 development and UWA development. This feature brings you yet another missing piece from the old world that you can now leverage in your modern apps.

Announcing UWP Community Toolkit 1.5

Today marks the sixth release of the UWP Community Toolkit – all packages are updated to version 1.5. Thanks to the UWP developer community, the UWP Community Toolkit has seen great improvements and stability to the existing controls and services. The community partnership has led to several new additions to this release.

To highlight a few of the new additions, the UWP Community Toolkit now includes:

  1. Menu: A classic control used by traditional desktop applications, adapted for the Universal Windows Platform. As requested by the community on UserVoice, the Menu allows the developer to provide a hierarchical list of menus and submenus that support any input modality and can adapt to the screen size to provide a natural and fluid interaction.
  2. OrbitView: A new ItemsControl that arranges elements around a center element and provides flexibility for size and distance for each element, as well as the ability to show orbits or anchors for each item.
  3. RadialProgressBar: A XAML Control that displays a value within a range using a circular sector that grows clockwise until it becomes a full ring. A fantastic variation of the ProgressBar.
  4. RoundImageEx: Similar to the ImageEx control, the RoundImageEx control downloads and locally caches images asynchronously while showing loading indicators. In addition, the RoundImageEx allows images to be clipped as circles.
  5. ExpressionBuilder: A type-safe way to build powerful composition ExpressionAnimation.
  6. BluetoothLEHelper: The BluetoothLEHelper class provides functionality to easily enumerate, connect to and interact with Bluetooth LE Peripherals.

For a complete overview of what’s new in version 1.5, please read our release notes on GitHub.

The release of Windows 10 Creators Update (build 10.0.15063) has enabled several new APIs that make it possible to improve several controls used in apps targeting the latest update. Therefore, several packages are now targeting the Windows 10 Creators Update and can take advantage of these new APIs. We encourage all developers using the toolkit to update their apps to the latest version of the UWP Community Toolkit.

As a reminder, the UWP Community Toolkit can be used in any UWP app across PC, Xbox One, mobile, HoloLens and Surface Hub devices. You can get started by following this tutorial, or preview the latest features by installing the UWP Community Toolkit Sample App from the Windows Store.

If you would like to contribute, please join us on GitHub!