Menangani aktivasi URI

  • Artikel

API penting

Pelajari cara mendaftarkan aplikasi untuk menjadi handler default untuk nama skema Uniform Resource Identifier (URI). Aplikasi desktop Windows dan aplikasi Platform Windows Universal (UWP) dapat mendaftar untuk menjadi handler default untuk nama skema URI. Jika pengguna memilih aplikasi Anda sebagai handler default untuk nama skema URI, aplikasi Anda akan diaktifkan setiap kali jenis URI tersebut diluncurkan.

Kami menyarankan agar Anda hanya mendaftar untuk nama skema URI jika Anda ingin menangani semua peluncuran URI untuk jenis skema URI tersebut. Jika Anda memilih untuk mendaftar untuk nama skema URI, Anda harus memberi pengguna akhir fungsionalitas yang diharapkan saat aplikasi Anda diaktifkan untuk skema URI tersebut. Misalnya, aplikasi yang mendaftar untuk mailto: Nama skema URI harus terbuka ke pesan email baru sehingga pengguna dapat membuat email baru. Untuk informasi selengkapnya tentang asosiasi URI, lihat Panduan dan daftar periksa untuk jenis file dan URI.

Langkah-langkah ini menunjukkan cara mendaftar untuk nama skema URI kustom, alsdk://, dan cara mengaktifkan aplikasi Anda saat pengguna meluncurkan alsdk:// URI.

Catatan

Di aplikasi UWP, URI dan ekstensi file tertentu dicadangkan untuk digunakan oleh aplikasi bawaan dan sistem operasi. Upaya untuk mendaftarkan aplikasi Anda dengan URI yang dipesan atau ekstensi file akan diabaikan. Lihat Nama skema URI khusus dan jenis file untuk daftar alfabet skema Uri yang tidak dapat Anda daftarkan untuk aplikasi UWP Anda karena dicadangkan atau dilarang.

Langkah 1: Tentukan titik ekstensi dalam manifes paket

Aplikasi ini menerima peristiwa aktivasi hanya untuk nama skema URI yang tercantum dalam manifes paket. Berikut adalah cara Anda menunjukkan bahwa aplikasi Anda menangani alsdk nama skema URI.

  1. Di Penjelajah Solusi, klik dua kali package.appxmanifest untuk membuka perancang manifes. Pilih tab Deklarasi dan di menu drop-down Deklarasi yang Tersedia , pilih Protokol lalu klik Tambahkan.

    Berikut adalah deskripsi singkat dari setiap bidang yang dapat Anda isi perancang manifes untuk Protokol (lihat Manifes Paket AppX untuk detailnya):

Bidang Deskripsi
Logo Tentukan logo yang digunakan untuk mengidentifikasi nama skema URI di Atur Program Default pada Panel Kontrol. Jika tidak ada Logo yang ditentukan, logo kecil untuk aplikasi akan digunakan.
Nama Tampilan Tentukan nama tampilan untuk mengidentifikasi nama skema URI di Atur Program Default pada Panel Kontrol.
Nama Pilih nama untuk skema Uri.
Catatan Nama harus dalam semua huruf kecil.
Jenis file yang dicadangkan dan terlarang Lihat Nama skema URI khusus dan jenis file untuk daftar alfabet skema Uri yang tidak dapat Anda daftarkan untuk aplikasi UWP Anda karena dicadangkan atau dilarang.
Eksekusi Menentukan peluncuran default yang dapat dieksekusi untuk protokol. Jika tidak ditentukan, executable aplikasi akan digunakan. Jika ditentukan, panjang string harus antara 1 dan 256 karakter, harus diakhir dengan ".exe", dan tidak boleh berisi karakter ini: >, , <:, ", |, ?, atau *. Jika ditentukan, Titik masuk juga digunakan. Jika Titik masuk tidak ditentukan, titik entri yang ditentukan untuk aplikasi akan digunakan.
Titik masuk Menentukan tugas yang menangani ekstensi protokol. Ini biasanya merupakan nama yang sepenuhnya memenuhi syarat namespace dari jenis Windows Runtime. Jika tidak ditentukan, titik masuk untuk aplikasi digunakan.
Halaman awal Halaman web yang menangani titik ekstensibilitas.
Grup Sumber Daya Tag yang dapat Anda gunakan untuk mengelompokkan aktivasi ekstensi bersama-sama untuk tujuan manajemen sumber daya.
Tampilan yang Diinginkan (khusus Windows) Tentukan bidang Tampilan yang Diinginkan untuk menunjukkan jumlah ruang yang dibutuhkan jendela aplikasi saat diluncurkan untuk nama skema URI. Nilai yang mungkin untuk Tampilan yang Diinginkan adalah Default, UseLess, UseHalf, UseMore, atau UseMinimum.
Catatan Windows memperhitungkan beberapa faktor berbeda saat menentukan ukuran jendela akhir aplikasi target, misalnya, preferensi aplikasi sumber, jumlah aplikasi di layar, orientasi layar, dan sebagainya. Pengaturan Tampilan yang Diinginkan tidak menjamin perilaku windowing tertentu untuk aplikasi target.
Keluarga perangkat seluler: Tampilan yang Diinginkan tidak didukung pada keluarga perangkat seluler.

  1. Masukkan images\Icon.png sebagai Logo.

  2. Masukkan SDK Sample URI Scheme sebagai Nama tampilan

  3. Masukkan alsdk sebagai Nama.

  4. Tekan Ctrl+S untuk menyimpan perubahan ke package.appxmanifest.

    Ini menambahkan elemen Extension seperti ini ke manifes paket. Kategori windows.protocol menunjukkan bahwa aplikasi menangani alsdk nama skema URI.

    <Applications>
        <Application Id= ... >
            <Extensions>
                <uap:Extension Category="windows.protocol">
                  <uap:Protocol Name="alsdk">
                    <uap:Logo>images\icon.png</uap:Logo>
                    <uap:DisplayName>SDK Sample URI Scheme</uap:DisplayName>
                  </uap:Protocol>
                </uap:Extension>
          </Extensions>
          ...
        </Application>
   <Applications>

Langkah 2: Tambahkan ikon yang tepat

Aplikasi yang menjadi default untuk nama skema URI memiliki ikon yang ditampilkan di berbagai tempat di seluruh sistem seperti di panel kontrol Program default. Sertakan ikon 44x44 dengan proyek Anda untuk tujuan ini. Cocokkan tampilan logo petak peta aplikasi dan gunakan warna latar belakang aplikasi Anda daripada membuat ikon transparan. Buat logo meluas ke tepi tanpa padding. Uji ikon Anda di latar belakang putih. Lihat Ikon dan logo aplikasi untuk detail selengkapnya tentang ikon.

Langkah 3: Menangani peristiwa yang diaktifkan

Penanganan aktivitas Aktif menerima semua peristiwa aktivasi. Properti Kind menunjukkan jenis peristiwa aktivasi. Contoh ini disiapkan untuk menangani peristiwa aktivasi Protokol .

public partial class App
{
   protected override void OnActivated(IActivatedEventArgs args)
  {
      if (args.Kind == ActivationKind.Protocol)
      {
         ProtocolActivatedEventArgs eventArgs = args as ProtocolActivatedEventArgs;
         // TODO: Handle URI activation
         // The received URI is eventArgs.Uri.AbsoluteUri
      }
   }
}

Protected Overrides Sub OnActivated(ByVal args As Windows.ApplicationModel.Activation.IActivatedEventArgs)
   If args.Kind = ActivationKind.Protocol Then
      ProtocolActivatedEventArgs eventArgs = args As ProtocolActivatedEventArgs
      
      ' TODO: Handle URI activation
      ' The received URI is eventArgs.Uri.AbsoluteUri
 End If
End Sub

void App::OnActivated(Windows::ApplicationModel::Activation::IActivatedEventArgs const& args)
{
    if (args.Kind() == Windows::ApplicationModel::Activation::ActivationKind::Protocol)
    {
        auto protocolActivatedEventArgs{ args.as<Windows::ApplicationModel::Activation::ProtocolActivatedEventArgs>() };
        // TODO: Handle URI activation  
        auto receivedURI{ protocolActivatedEventArgs.Uri().RawUri() };
    }
}

void App::OnActivated(Windows::ApplicationModel::Activation::IActivatedEventArgs^ args)
{
   if (args->Kind == Windows::ApplicationModel::Activation::ActivationKind::Protocol)
   {
      Windows::ApplicationModel::Activation::ProtocolActivatedEventArgs^ eventArgs =
          dynamic_cast<Windows::ApplicationModel::Activation::ProtocolActivatedEventArgs^>(args);
      
      // TODO: Handle URI activation  
      // The received URI is eventArgs->Uri->RawUri
   }
}

Catatan

Saat diluncurkan melalui Kontrak Protokol, pastikan bahwa tombol Kembali membawa pengguna kembali ke layar yang meluncurkan aplikasi dan bukan ke konten aplikasi sebelumnya.

Kode berikut secara terprogram meluncurkan aplikasi melalui URI-nya:

   // Launch the URI
   var uri = new Uri("alsdk:");
   var success = await Windows.System.Launcher.LaunchUriAsync(uri)

Untuk detail selengkapnya tentang cara meluncurkan aplikasi melalui URI, lihat Meluncurkan aplikasi default untuk URI.

Disarankan agar aplikasi membuat Bingkai XAML baru untuk setiap peristiwa aktivasi yang membuka halaman baru. Dengan cara ini, tumpukan belakang navigasi untuk Bingkai XAML baru tidak akan berisi konten sebelumnya yang mungkin dimiliki aplikasi di jendela saat ini saat ditangguhkan. Aplikasi yang memutuskan untuk menggunakan Satu Bingkai XAML untuk Peluncuran dan Kontrak File harus menghapus halaman pada jurnal navigasi Bingkai sebelum menavigasi ke halaman baru.

Saat diluncurkan melalui aktivasi Protokol, aplikasi harus mempertimbangkan termasuk UI yang memungkinkan pengguna untuk kembali ke halaman atas aplikasi.

Keterangan

Aplikasi atau situs web apa pun dapat menggunakan nama skema URI Anda, termasuk yang berbahaya. Jadi setiap data yang Anda dapatkan di URI bisa berasal dari sumber yang tidak tepercaya. Kami menyarankan agar Anda tidak pernah melakukan tindakan permanen berdasarkan parameter yang Anda terima di URI. Misalnya, parameter URI dapat digunakan untuk meluncurkan aplikasi ke halaman akun pengguna, tetapi kami sarankan Anda tidak pernah menggunakannya untuk langsung memodifikasi akun pengguna.

Catatan

Jika Anda membuat nama skema URI baru untuk aplikasi Anda, pastikan untuk mengikuti panduan di RFC 4395. Ini memastikan bahwa nama Anda memenuhi standar untuk skema URI.

Catatan

Saat diluncurkan melalui Kontrak Protokol, pastikan bahwa tombol Kembali membawa pengguna kembali ke layar yang meluncurkan aplikasi dan bukan ke konten aplikasi sebelumnya.

Sebaiknya aplikasi membuat Bingkai XAML baru untuk setiap peristiwa aktivasi yang membuka target Uri baru. Dengan cara ini, tumpukan belakang navigasi untuk Bingkai XAML baru tidak akan berisi konten sebelumnya yang mungkin dimiliki aplikasi di jendela saat ini saat ditangguhkan.

Jika Anda memutuskan bahwa Anda ingin aplikasi Anda menggunakan satu Bingkai XAML untuk Kontrak Peluncuran dan Protokol, hapus halaman pada jurnal navigasi Bingkai sebelum menavigasi ke halaman baru. Saat diluncurkan melalui Kontrak Protokol, pertimbangkan untuk menyertakan UI ke dalam aplikasi Anda yang memungkinkan pengguna untuk kembali ke bagian atas aplikasi.

Aplikasi sampel lengkap

Konsep

Tugas

Panduan

Referensi