Menangani aktivasi protokol URI di aplikasi .NET

Aktivasi protokol (juga disebut penautan mendalam atau aktivasi URI) memungkinkan aplikasi lain, browser, atau baris perintah meluncurkan aplikasi Anda dengan menavigasi ke URI seperti myapp://action?param=value.

Artikel ini memperlihatkan kode khusus untuk aplikasi WPF. Untuk panduan lengkap, lihat artikel aktivasi Handle URI utama. Untuk detail lengkap tentang aktivasi kaya dengan SDK Aplikasi Windows, lihat aktivasi Rich dengan API siklus hidup aplikasi.

Mendaftar untuk aktivasi protokol

Anda harus mendaftarkan aplikasi untuk menangani aktivasi protokol. Untuk aplikasi yang tidak dikemas, Anda mendaftarkannya dalam kode. Untuk aplikasi paket, Anda mendaftar di manifes aplikasi.

Aplikasi tanpa kemasan

Untuk aplikasi .NET yang tidak dikemas (penyiapan WPF/WinForms default), daftarkan protokol Anda saat startup menggunakan ActivationRegistrationManager. Pendaftaran dilakukan untuk setiap pengguna dan tetap aktif, sehingga aman untuk memanggil ini setiap kali aplikasi dimulai.

Dalam App.xaml.cs, menggantikan 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);
}

Untuk membersihkan pendaftaran (misalnya, dalam langkah penghapusan instalasi), panggil ActivationRegistrationManager.UnregisterForProtocolActivation("myapp", "").

Aplikasi kemasan

Untuk aplikasi .NET yang dikemas, deklarasikan protokol dalam Package.appxmanifest di bawah elemen <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>

Pastikan uap namespace XML dideklarasikan pada Package elemen: xmlns:uap="http://schemas.microsoft.com/appx/manifest/uap/windows10".

Menangani aktivasi

Ambil argumen aktivasi menggunakan AppInstance.GetCurrent(). GetActivatedEventArgs. Contoh berikut mencakup kode untuk aplikasi WPF yang tidak dikemas, yang memanggil RegisterForProtocolActivation saat startup. Aplikasi paket menerima aktivasi melalui pendaftaran manifest, sehingga mereka dapat melewati panggilan RegisterForProtocolActivation.

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.
}

Note

aplikasi WPF dan Formulir Windows harus memanggil AppInstance.GetCurrent().GetActivatedEventArgs() untuk mengambil data aktivasi URI. Tidak seperti aplikasi C++ Win32, aplikasi .NET tidak menerima argumen aktivasi melalui parameter titik masuk startup.

Menangani pengalihan satu instans

Jika aplikasi Anda hanya boleh menjalankan satu instans pada satu waktu, gunakan AppInstance.FindOrRegisterForKey untuk mengalihkan peluncuran URI berikutnya ke instans yang sedang berjalan:

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();
    });
}

Untuk informasi selengkapnya tentang instancing aplikasi, lihat Instancing aplikasi dengan API siklus hidup aplikasi.

Konten terkait

  • Last updated on