Command-Line Activation of Universal Windows Apps

[News]

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.

Link Removed

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.

Link Removed

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.

Link Removed

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

Link Removed

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

Link Removed

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.

Continue reading...