Training
Module
Manage Universal Windows Platform apps - Training
This module explores using Microsoft Store to manage Universal Windows Platform apps.
This browser is no longer supported.
Upgrade to Microsoft Edge to take advantage of the latest features, security updates, and technical support.
This topic describes how to create multi-instance Universal Windows Platform (UWP) apps.
From Windows 10, version 1803 (10.0; Build 17134) onward, your UWP app can opt in to support multiple instances. If an instance of an multi-instance UWP app is running, and a subsequent activation request comes through, the platform will not activate the existing instance. Instead, it will create a new instance, running in a separate process.
Important
Multi-instancing is supported for JavaScript applications, but multi-instancing redirection is not. Since multi-instancing redirection is not supported for JavaScript applications, the AppInstance class is not useful for such applications.
If you are creating a new multi-instance application, you can install the Multi-Instance App Project Templates.VSIX, available from the Visual Studio Marketplace. Once you install the templates, they will be available in the New Project dialog under Visual C# > Windows Universal (or Other Languages > Visual C++ > Windows Universal).
Note
The Multi-Instance App Project template is no longer available. The VSIX template was a convenience, so you will need to modify the existing project instead, as described below. Be certain to add the DISABLE_XAML_GENERATED_MAIN constant to the project build symbols, as this prevents the build from generating a default Main(). This allows used of a specially written app-specific version of Main().
Two templates are installed: Multi-Instance UWP app, which provides the template for creating a multi-instance app, and Multi-Instance Redirection UWP app, which provides additional logic that you can build on to either launch a new instance or selectively activate an instance that has already been launched. For example, perhaps you only want one instance at a time editing the same document, so you bring the instance that has that file open to the foreground rather than launching a new instance.
Both templates add SupportsMultipleInstances
to the package.appxmanifest
file. Note the namespace prefix desktop4
and iot2
: only projects that target the desktop, or Internet of Things (IoT) projects, support multi-instancing.
<Package
...
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">
...
<Applications>
<Application Id="App"
...
desktop4:SupportsMultipleInstances="true"
iot2:SupportsMultipleInstances="true">
...
</Application>
</Applications>
...
</Package>
Multi-instancing support for UWP apps goes beyond simply making it possible to launch multiple instances of the app. It allows for customization in cases where you want to select whether a new instance of your app is launched or an instance that is already running is activated. For example, if the app is launched to edit a file that is already being edited in another instance, you may want to redirect the activation to that instance instead of opening up another instance that that is already editing the file.
To see it in action, watch this video about Creating multi-instance UWP apps.
The Multi-Instance Redirection UWP app template adds SupportsMultipleInstances
to the package.appxmanifest file as shown above, and also adds a Program.cs (or Program.cpp, if you are using the C++ version of the template) to your project that contains a Main()
function. The logic for redirecting activation goes in the Main
function. The template for Program.cs is shown below.
The AppInstance.RecommendedInstance property represents the shell-provided preferred instance for this activation request, if there is one (or null
if there isn't one). If the shell provides a preference, then you can redirect activation to that instance, or you can ignore it if you choose.
public static class Program
{
// 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();
// If the Windows shell indicates a recommended instance, then
// the app can choose to redirect this activation to that instance instead.
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 = Guid.NewGuid().ToString(); // always unique.
//string key = "Some-App-Defined-Key"; // never unique.
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();
}
}
}
}
Main()
is the first thing that runs. It runs before OnLaunched and OnActivated. This allows you to determine whether to activate this, or another instance, before any other initialization code in your app runs.
The code above determines whether an existing, or new, instance of your application is activated. A key is used to determine whether there is an existing instance that you want to activate. For example, if your app can be launched to Handle file activation, you might use the file name as a key. Then you can check whether an instance of your app is already registered with that key and activate it instead of opening a new instance. This is the idea behind the code: var instance = AppInstance.FindOrRegisterInstanceForKey(key);
If an instance registered with the key is found, then that instance is activated. If the key is not found, then the current instance (the instance that is currently running Main
) creates its application object and starts running.
SupportsMultipleInstances
in its Package.appxmanifest file, then its extensions do not need to declare SupportsMultipleInstances
.SupportsMultipleInstances
to any other extension, apart from background tasks or app-services, and the app that hosts the extension doesn't also declare SupportsMultipleInstances
in its Package.appxmanifest file, then a schema error is generated.SupportsMultipleInstances
and ResourceGroup
in their manifest.See Multi-Instance sample for an example of multi-instance activation redirection.
AppInstance.FindOrRegisterInstanceForKey AppInstance.GetActivatedEventArgs AppInstance.RedirectActivationTo Handle app activation
Training
Module
Manage Universal Windows Platform apps - Training
This module explores using Microsoft Store to manage Universal Windows Platform apps.