Aplicativos de várias instâncias com SDK do Aplicativo Windows

Por padrão, um aplicativo da área de trabalho SDK do Aplicativo Windows pode executar várias instâncias simultaneamente. Cada instância é executada como um processo separado. Você pode controlar esse comportamento usando o Microsoft.Windows. Classe AppLifecycle.AppInstance para registrar instâncias, detectar as existentes e redirecionar ativações.

Cenários para gerenciamento de várias instâncias

• Garantia de instância única — Redirecione novas ativações para a instância já em execução.
• Roteamento baseado em chave – rotear arquivos ou URIs diferentes para instâncias específicas (por exemplo, uma instância por documento).
• Descoberta de instância – enumerar todas as instâncias em execução para coordenar o trabalho.

Registrar uma instância com uma chave

Use AppInstance.FindOrRegisterForKey no método Main do seu aplicativo para reivindicar uma chave. Se a chave já estiver registrada por outra instância, você poderá redirecionar a ativação. O método personalizado Main a seguir fica em Program.cs, antes de qualquer inicialização de XAML:

using Microsoft.Windows.AppLifecycle;

public static class Program
{

[STAThread]
static async Task Main(string[] args)
{
    // Required before calling any other Windows App SDK or WinRT API
    // from a custom entry point.
    WinRT.ComWrappersSupport.InitializeComWrappers();

    // Determine a key for this activation
    string instanceKey = "main-instance";

    var activatedArgs = AppInstance.GetCurrent().GetActivatedEventArgs();
    if (activatedArgs.Kind == ExtendedActivationKind.File)
    {
        var fileArgs = activatedArgs.Data as
            Windows.ApplicationModel.Activation.IFileActivatedEventArgs;
        // Use the file path as the instance key to route
        // each file to its own instance
        if (fileArgs?.Files is { Count: > 0 })
        {
            instanceKey = fileArgs.Files[0].Path;
        }
    }

    var instance = AppInstance.FindOrRegisterForKey(instanceKey);

    if (!instance.IsCurrent)
    {
        // Another instance owns this key — redirect activation to it
        await instance.RedirectActivationToAsync(activatedArgs);
        return; // Exit this process
    }

    // This instance owns the key — proceed with normal startup
    // Register for future redirected activations
    instance.Activated += OnActivated;

    Application.Start((p) =>
    {
        var context = new DispatcherQueueSynchronizationContext(
            DispatcherQueue.GetForCurrentThread());
        SynchronizationContext.SetSynchronizationContext(context);
        _ = new App();
    });
}

private static void OnActivated(object? sender, AppActivationArguments args)
{
    // Handle the redirected activation on the UI thread
    // For example, open the file or navigate to the URI
}

// App is the application type generated by the WinUI 3 project template
// (App.xaml / App.xaml.cs).
private partial class App : Microsoft.UI.Xaml.Application
{
}

}

Forçar comportamento de instância única

Para tornar seu aplicativo de instância única, sempre use a mesma chave:

var instance = AppInstance.FindOrRegisterForKey("single-instance");

if (!instance.IsCurrent)
{
    await instance.RedirectActivationToAsync(
        AppInstance.GetCurrent().GetActivatedEventArgs());
    return;
}

Enumerar instâncias em execução

Use AppInstance.GetInstances() para descobrir todas as instâncias registradas:

var instances = AppInstance.GetInstances();
foreach (var inst in instances)
{
    System.Diagnostics.Debug.WriteLine(
        $"Key: {inst.Key}, ProcessId: {inst.ProcessId}");
}

Desregistrar uma instância

Quando sua instância é desligada, o registro é removido automaticamente. Você também pode cancelar o registro explicitamente:

AppInstance.GetCurrent().UnregisterKey();

Diferenças em relação à UWP com suporte a múltiplas instâncias

Conteúdo relacionado

• Ciclo de vida do aplicativo para SDK do Aplicativo Windows
• Ativação do aplicativo para SDK do Aplicativo Windows
• Instanciação de aplicativo no SDK do Aplicativo Windows