Controlar la activación del protocolo URI en una aplicación de .NET

La activación del protocolo (también denominada vinculación profunda o activación de URI) permite que otra aplicación, un explorador o la línea de comandos inicien la aplicación navegando a un URI como myapp://action?param=value.

En este artículo se muestra código específicamente para una aplicación de WPF. Para obtener instrucciones completas, consulte el artículo principal Sobre la activación de identificador URI . Para más información sobre la activación enriquecida con el SDK de Aplicaciones para Windows, consulte Rich activation with the app lifecycle API.

Registro para la activación del protocolo

Debes registrar la aplicación para controlar la activación del protocolo. Para una aplicación sin empaquetar, se registra en el código. En el caso de una aplicación empaquetada, el registro se realiza en el manifiesto de la aplicación.

Aplicación sin empaquetar

Para una aplicación de .NET sin empaquetar (la configuración predeterminada WPF/WinForms), registre el protocolo en el inicio mediante ActivationRegistrationManager. Los registros son por usuario y persisten, por lo que es seguro llamar a esto en cada inicio.

En App.xaml.cs, sobrescriba OnStartup:

using Microsoft.Windows.AppLifecycle;

protected override void OnStartup(StartupEventArgs e)
{
    // Register the URI scheme "myapp://" for this app.
    // For the logo, pass the exe path + resource index (or "" to use the default icon).
    string exePath = System.Diagnostics.Process.GetCurrentProcess().MainModule?.FileName ?? "";
    string logo = string.IsNullOrEmpty(exePath) ? "" : exePath + ",0";
    ActivationRegistrationManager.RegisterForProtocolActivation(
        "myapp",                // URI scheme (no "://")
        logo,                   // logo: exe path + resource index, or "" for default icon
        "My App",               // display name for the protocol
        exePath);               // path of this EXE; pass "" to default to the current process

    base.OnStartup(e);
}

Para limpiar el registro (por ejemplo, en un paso de desinstalación), llame a ActivationRegistrationManager.UnregisterForProtocolActivation("myapp", "").

Aplicación empaquetada

Para una aplicación de .NET empaquetada, declare el protocolo en `Package.appxmanifest` dentro del elemento `<Applications><Application>`.

<Applications>
  <Application ...>
    <Extensions>
      <uap:Extension Category="windows.protocol">
        <uap:Protocol Name="myapp">
          <uap:DisplayName>My App</uap:DisplayName>
        </uap:Protocol>
      </uap:Extension>
    </Extensions>
  </Application>
</Applications>

Asegúrese de que el uap espacio de nombres XML sea declarado en el elemento Package:xmlns:uap="http://schemas.microsoft.com/appx/manifest/uap/windows10".

Control de la activación

Recupere los argumentos de activación mediante AppInstance.GetCurrent(). GetActivatedEventArgs. En el ejemplo siguiente se incluye código para una aplicación de WPF sin empaquetar, que llama a RegisterForProtocolActivation en el inicio. Las aplicaciones empaquetadas reciben la activación a través del registro del manifiesto, por lo que pueden omitir la RegisterForProtocolActivation llamada.

using Microsoft.Windows.AppLifecycle;
using Windows.ApplicationModel.Activation;

protected override void OnStartup(StartupEventArgs e)
{
    // Unpackaged apps only: register the protocol at startup.
    // Packaged apps (MSIX): skip these lines — the manifest handles registration.
    string exePath = System.Diagnostics.Process.GetCurrentProcess().MainModule?.FileName ?? "";
    string logo = string.IsNullOrEmpty(exePath) ? "" : exePath + ",0";
    ActivationRegistrationManager.RegisterForProtocolActivation(
        "myapp", logo, "My App", exePath);

    // Get the activation args for this specific launch.
    AppActivationArguments args = AppInstance.GetCurrent().GetActivatedEventArgs();
    if (args?.Kind == ExtendedActivationKind.Protocol)
    {
        var protocolArgs = (ProtocolActivatedEventArgs)args.Data;
        HandleProtocolActivation(protocolArgs.Uri);
    }

    base.OnStartup(e);
}

private void HandleProtocolActivation(Uri uri)
{
    // Navigate to or open content based on uri.AbsolutePath or uri.Query.
}

Nota:

Las aplicaciones WPF y Windows Forms deben llamar a AppInstance.GetCurrent().GetActivatedEventArgs() para recuperar datos de activación de URI. A diferencia de las aplicaciones Win32 de C++, las aplicaciones .NET no reciben argumentos de activación a través de un parámetro de punto de entrada de inicio.

Gestión de la redirección de instancia única

Si la aplicación solo debe ejecutar una instancia cada vez, use AppInstance.FindOrRegisterForKey para redirigir los inicios posteriores del URI a la instancia en ejecución:

protected override void OnStartup(StartupEventArgs e)
{
    string exePath = System.Diagnostics.Process.GetCurrentProcess().MainModule?.FileName ?? "";
    string logo = string.IsNullOrEmpty(exePath) ? "" : exePath + ",0";
    ActivationRegistrationManager.RegisterForProtocolActivation(
        "myapp", logo, "My App", exePath);

    // Try to claim the "main" key. If another instance already has it, redirect and exit.
    AppInstance currentInstance = AppInstance.FindOrRegisterForKey("main");
    if (!currentInstance.IsCurrent)
    {
        var activationArgs = AppInstance.GetCurrent().GetActivatedEventArgs();
        // Run the async redirect on a thread-pool thread to avoid a potential deadlock
        // with the WPF SynchronizationContext. Signal completion via an event so that
        // this code path exits cleanly without re-entering the STA message pump.
        var redirectCompleted = new System.Threading.ManualResetEventSlim(false);
        System.Threading.Tasks.Task.Run(async () =>
        {
            await currentInstance.RedirectActivationToAsync(activationArgs);
            redirectCompleted.Set();
        });
        redirectCompleted.Wait();
        Shutdown();
        return;
    }

    // This is the first instance. Subscribe to future activations.
    currentInstance.Activated += OnActivated;
    base.OnStartup(e);
}

private void OnActivated(object sender, AppActivationArguments args)
{
    Dispatcher.Invoke(() =>
    {
        if (args.Kind == ExtendedActivationKind.Protocol)
        {
            var protocolArgs = (ProtocolActivatedEventArgs)args.Data;
            HandleProtocolActivation(protocolArgs.Uri);
        }
        MainWindow?.Activate();
    });
}

Para obtener más información sobre la creación de instancias de aplicaciones, consulte Creación de instancias de aplicaciones con la API del ciclo de vida de la aplicación.

Contenido relacionado

  • Last updated on