One thing that went unnoticed in the last post is that the console app is multi-instance: if you click in the live tile or in the start menu, instead of bringing the same app to the front, you are opening a new window and running a new instance of it. This is something new for UWP apps: until now, you could only have one instance of the app running in your machine. While this works for many apps, when you are developing an LOB app, for example, you may need to open more than one instance and that can be limiting. The SDK released in the Aril 2018 update allow you to create multi instanced apps.
Single instance apps
The default UWP apps have a single instance. When you activate it for the first time, it opens the main window and runs the app. After the second call, the same app is activated and you can handle the activation in the OnLaunched method, like this:
private int _activationNo;
/// <summary>
/// Invoked when the application is launched normally by the end user. Other entry points
/// will be used such as when the application is launched to open a specific file.
/// </summary>
/// <param name="e">Details about the launch request and process.</param>
protected override void OnLaunched(LaunchActivatedEventArgs e)
{
Frame rootFrame = Window.Current.Content as Frame;
// Do not repeat app initialization when the Window already has content,
// just ensure that the window is active
if (rootFrame == null)
{
// Create a Frame to act as the navigation context and navigate to the first page
rootFrame = new Frame();
rootFrame.NavigationFailed += OnNavigationFailed;
if (e.PreviousExecutionState == ApplicationExecutionState.Terminated)
{
//TODO: Load state from previously suspended application
}
// Place the frame in the current Window
Window.Current.Content = rootFrame;
}
if (e.PrelaunchActivated == false)
{
if (rootFrame.Content == null)
{
// When the navigation stack isn't restored navigate to the first page,
// configuring the new page by passing required information as a navigation
// parameter
rootFrame.Navigate(typeof(MainPage), e.Arguments);
}
if (rootFrame.Content is MainPage page)
page.MainText =
$"Activation# {++_activationNo}";
// Ensure the current window is active
Window.Current.Activate();
}
}
This way, you will see the activation number in the main page for the app. The app continues to have a single page, but you can control the number of times it’s activated. One other way to handle this is to open multiple windows, one for each activation. It is done like this:
private int _activationNo;
/// <summary>
/// Invoked when the application is launched normally by the end user. Other entry points
/// will be used such as when the application is launched to open a specific file.
/// </summary>
/// <param name="e">Details about the launch request and process.</param>
protected override void OnLaunched(LaunchActivatedEventArgs e)
{
Frame rootFrame = Window.Current.Content as Frame;
// Do not repeat app initialization when the Window already has content,
// just ensure that the window is active
if (rootFrame == null)
{
// Create a Frame to act as the navigation context and navigate to the first page
rootFrame = new Frame();
rootFrame.NavigationFailed += OnNavigationFailed;
if (e.PreviousExecutionState == ApplicationExecutionState.Terminated)
{
//TODO: Load state from previously suspended application
}
// Place the frame in the current Window
Window.Current.Content = rootFrame;
}
if (e.PrelaunchActivated == false)
{
if (rootFrame.Content == null)
{
// When the navigation stack isn't restored navigate to the first page,
// configuring the new page by passing required information as a navigation
// parameter
rootFrame.Navigate(typeof(MainPage), e.Arguments);
if (rootFrame.Content is MainPage page)
page.MainText =
$"Activation# {++_activationNo}";
// Ensure the current window is active
Window.Current.Activate();
}
else
{
CreateNewView();
}
}
}
private async void CreateNewView()
{
CoreApplicationView newView = CoreApplication.CreateNewView();
int newViewId = 0;
await newView.Dispatcher.RunAsync(CoreDispatcherPriority.Normal, () =>
{
Frame frame = new Frame();
frame.Navigate(typeof(MainPage), null);
Window.Current.Content = frame;
if (frame.Content is MainPage page)
page.MainText =
$"Activation# {++_activationNo}";
// You have to activate the window in order to show it later.
Window.Current.Activate();
newViewId = ApplicationView.GetForCurrentView().Id;
});
await ApplicationViewSwitcher.TryShowAsStandaloneAsync(newViewId);
}
The process is similar to the previous ones, but there is a difference: for the first activation, it fills the main window, and if not, it creates a new window with the CreateNewView method, then fills its content in the same way it did for the main window. After the window and the view are created and activated, we call ApplicationViewSwitcher.TryShowAsStandaloneAsync to show it. This will show the new window for the app.
This arrangement works fine, but there is a problem, here: all windows are in the same process and, if you have a problem in one of them, all will crash. This may not be what you want, and it’s changed in the April 2018 update – you can have multi-instance UWP apps.
Multi-Instance apps
The main difference is the SupportsMultipleInstances attribute in the package.appxmanifest file, in the Application node:
<Application Id="App" Executable="$targetnametoken$.exe" EntryPoint="MultiInstance.Program" desktop4:SupportsMultipleInstances="true" iot2:SupportsMultipleInstances="true">
The desktop4 and iot2 namespaces are defined in the Package node:
<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" xmlns:desktop4="http://schemas.microsoft.com/appx/manifest/desktop/windows10/4" xmlns:iot2="http://schemas.microsoft.com/appx/manifest/iot/windows10/2" IgnorableNamespaces="uap mp uap5 iot2 desktop4">
Once you put these in your package.appxmanifest, your application will be multi-instanced:
If you don’t want to add this data manually, you can install the Multi-Instance templates, created by Microsoft. In Visual Studio, go to Tools/Extensions and Updates and install the Multi-Instance template:
Once you do that, you will get two new UWP templates, the Multi-Instance UWP App and Multi-Instance UWP Redirection App:
The Multi-Instance UWP App template does what we did before: creates a blank app with the new attribute. The Multi-Instance Redirection UWP App is a bit more complex. Sometimes you want to handle how multi instancing works and call a specific instance. In this case, the template generates a Program.cs file with a Main method, where you can handle the redirection.
public static class Program
{
// This project includes DISABLE_XAML_GENERATED_MAIN in the build properties,
// which prevents the build system from generating the default Main method:
//static void Main(string[] args)
//{
// global::Windows.UI.Xaml.Application.Start((p) => new App());
//}
// This example code shows how you could implement the required Main method to
// support multi-instance redirection. The minimum requirement is to call
// Application.Start with a new App object. Beyond that, you may delete the
// rest of the example code and replace it with your custom code if you wish.
static void Main(string[] args)
{
// First, we'll get our activation event args, which are typically richer
// than the incoming command-line args. We can use these in our app-defined
// logic for generating the key for this instance.
IActivatedEventArgs activatedArgs = AppInstance.GetActivatedEventArgs();
// In some scenarios, the platform might indicate a recommended instance.
// If so, we can redirect this activation to that instance instead, if we wish.
if (AppInstance.RecommendedInstance != null)
{
AppInstance.RecommendedInstance.RedirectActivationTo();
}
else
{
// Define a key for this instance, based on some app-specific logic.
// If the key is always unique, then the app will never redirect.
// If the key is always non-unique, then the app will always redirect
// to the first instance. In practice, the app should produce a key
// that is sometimes unique and sometimes not, depending on its own needs.
uint number = CryptographicBuffer.GenerateRandomNumber();
string key = (number % 2 == 0) ? "even" : "odd";
var instance = AppInstance.FindOrRegisterInstanceForKey(key);
if (instance.IsCurrentInstance)
{
// If we successfully registered this instance, we can now just
// go ahead and do normal XAML initialization.
global::Windows.UI.Xaml.Application.Start((p) => new App());
}
else
{
// Some other instance has registered for this key, so we'll
// redirect this activation to that instance instead.
instance.RedirectActivationTo();
}
}
}
}
From the comments in the file, you can see that you can get the default behavior just by using this code in the Main method:
static void Main(string[] args)
{
global::Windows.UI.Xaml.Application.Start((p) => new App());
}
The key will be linked to the instance you want. For example, if you generate only different keys, new instances will be opened, and if you generate only one key, the first instance will be called. You can control how many instances you want and which ones you want to activate by using the keys you generate. For example, this code will allow you to have three instances open and will call them in a round-robin scheme:
static void Main(string[] args)
{
// First, we'll get our activation event args, which are typically richer
// than the incoming command-line args. We can use these in our app-defined
// logic for generating the key for this instance.
IActivatedEventArgs activatedArgs = AppInstance.GetActivatedEventArgs();
// In some scenarios, the platform might indicate a recommended instance.
// If so, we can redirect this activation to that instance instead, if we wish.
if (AppInstance.RecommendedInstance != null)
{
AppInstance.RecommendedInstance.RedirectActivationTo();
}
else
{
// Define a key for this instance, based on some app-specific logic.
// If the key is always unique, then the app will never redirect.
// If the key is always non-unique, then the app will always redirect
// to the first instance. In practice, the app should produce a key
// that is sometimes unique and sometimes not, depending on its own needs.
var instanceNo = GetInstanceNo();
string key = instanceNo.ToString();
var instance = AppInstance.FindOrRegisterInstanceForKey(key);
if (instance.IsCurrentInstance)
{
// If we successfully registered this instance, we can now just
// go ahead and do normal XAML initialization.
global::Windows.UI.Xaml.Application.Start(p => new App());
}
else
{
// Some other instance has registered for this key, so we'll
// redirect this activation to that instance instead.
instance.RedirectActivationTo();
}
}
}
private static int GetInstanceNo()
{
ApplicationDataContainer localSettings = ApplicationData.Current.LocalSettings;
var instanceNo = 0;
object data = localSettings.Values["instanceNo"];
if (data != null)
{
instanceNo = ((int)localSettings.Values["instanceNo"] + 1) % 3;
}
localSettings.Values["instanceNo"] = instanceNo;
return instanceNo;
}
In this case, we are keeping it simple, but we can make something more complex here. For example, we can activate some instance depending on the parameters passed to the application:
static void Main(string[] args)
{
// First, we'll get our activation event args, which are typically richer
// than the incoming command-line args. We can use these in our app-defined
// logic for generating the key for this instance.
IActivatedEventArgs activatedArgs = AppInstance.GetActivatedEventArgs();
// In some scenarios, the platform might indicate a recommended instance.
// If so, we can redirect this activation to that instance instead, if we wish.
if (AppInstance.RecommendedInstance != null)
{
AppInstance.RecommendedInstance.RedirectActivationTo();
}
else
{
// Define a key for this instance, based on some app-specific logic.
// If the key is always unique, then the app will never redirect.
// If the key is always non-unique, then the app will always redirect
// to the first instance. In practice, the app should produce a key
// that is sometimes unique and sometimes not, depending on its own needs.
string key = "MainInstance";
if (args.Length > 0)
key = args[0];
var instance = AppInstance.FindOrRegisterInstanceForKey(key);
if (instance.IsCurrentInstance)
{
// If we successfully registered this instance, we can now just
// go ahead and do normal XAML initialization.
global::Windows.UI.Xaml.Application.Start(p => new App());
}
else
{
// Some other instance has registered for this key, so we'll
// redirect this activation to that instance instead.
instance.RedirectActivationTo();
}
}
}
The key for the instance depends on the first parameter passed to the app. If we change our package.appxmanifest to add an ExecutionAlias, we can open a console window and call the app with a parameter:
<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"
xmlns:desktop4="http://schemas.microsoft.com/appx/manifest/desktop/windows10/4"
xmlns:iot2="http://schemas.microsoft.com/appx/manifest/iot/windows10/2"
IgnorableNamespaces="uap mp desktop4 iot2 uap5">
....
<Extensions>
<uap5:Extension
Category="windows.appExecutionAlias"
Executable="MultiInstance.exe"
EntryPoint="MultiInstance.App">
<uap5:AppExecutionAlias>
<uap5:ExecutionAlias Alias="MultiInstance.exe" />
</uap5:AppExecutionAlias>
</uap5:Extension>
</Extensions>
</Application>
Now, we can handle different instances of our app. If we want to process the arguments (for example, to open a different file depending on the passed parameter), we can do it in the App.xaml.cs. Please note that the OnLaunched method is not called when the app is activated from the command line. In this case, you must override the OnActivated method and process the arguments from there:
protected override void OnActivated(IActivatedEventArgs args)
{
var arguments = (args as CommandLineActivatedEventArgs)?.Operation.Arguments;
Frame rootFrame = Window.Current.Content as Frame;
if (rootFrame == null)
{
rootFrame = new Frame();
Window.Current.Content = rootFrame;
}
if (rootFrame.Content == null)
{
rootFrame.Navigate(typeof(MainPage),
$"Activated Kind {args.Kind}\nArguments: {arguments}");
}
Window.Current.Activate();
}
The processing of the arguments in the main page are done in the OnNavigatedTo method in MainPage.xaml.cs:
protected override void OnNavigatedTo(NavigationEventArgs e)
{
var param = e?.Parameter;
MainTxt.Text = param?.ToString() ?? "";
base.OnNavigatedTo(e);
}
Now, if we open a command line window and type something like MultiInstance “this is a test”, the program will open a new instance with the arguments:
Conclusions
As you can see, this new feature brings a lot of flexibility to your app. You already had the possibility to create many windows and now you can even create new instances and redirect the app to the right instance, depending on how the app is launched.
The full source code is available in http://github.com/bsonnino/MultiInstanceUWP
