Paket opsional dan penulisan set terkait

  • Artikel

Paket opsional berisi konten yang dapat diintegrasikan dengan paket utama. Ini berguna untuk konten yang dapat diunduh (DLC), membandingkan aplikasi besar untuk batasan ukuran, atau untuk mengirim konten tambahan apa pun yang terpisah dari aplikasi asli Anda. Untuk informasi selengkapnya tentang paket opsional, lihat Posting blog: Memperluas aplikasi Anda menggunakan paket opsional.

Set terkait adalah ekstensi paket opsional. Set terkait memungkinkan Anda menerapkan serangkaian versi yang ketat di seluruh paket utama dan opsional. Set terkait dapat memiliki penerbit yang berbeda dari aplikasi utama jika disebarkan di luar Toko. Untuk informasi selengkapnya tentang set terkait, lihat Postingan blog: Alat untuk membuat set terkait.

Paket opsional dan set terkait semuanya berjalan di dalam kontainer MSIX aplikasi utama.

Prasyarat

  • Visual Studio 2019 atau Visual Studio 2017 (versi 15.1 atau yang lebih baru)
  • Windows 10, versi 1703 atau yang lebih baru
  • Windows 10, SDK versi 1703 atau yang lebih baru

Untuk mendapatkan semua alat pengembangan terbaru, lihat Unduhan dan alat untuk Windows 10.

Catatan

Untuk mengirimkan aplikasi yang menggunakan paket opsional dan/atau set terkait ke Microsoft Store, Anda akan memerlukan izin. Paket opsional dan set terkait dapat digunakan untuk aplikasi Line of Business (LOB) atau perusahaan tanpa izin Pusat Mitra jika tidak dikirimkan ke Store. Lihat Dukungan pengembang Windows untuk mendapatkan izin untuk mengirimkan aplikasi yang menggunakan paket opsional dan set terkait.

Sampel kode

Saat Anda membaca artikel ini, disarankan agar Anda mengikuti sampel kode paket opsional di GitHub untuk pemahaman langsung tentang cara kerja paket opsional dan set terkait dalam Visual Studio.

Paket opsional

Untuk membuat paket opsional di Visual Studio, Anda harus:

  1. Pastikan Versi Min Platform Target aplikasi Anda diatur ke: 10.0.15063.0 atau yang lebih tinggi.
  2. Dari proyek paket utama Anda, buka Package.appxmanifest file . Navigasi ke tab "Kemasan" dan catat nama keluarga paket Anda, yang merupakan segalanya sebelum karakter "_".
  3. Dari proyek paket opsional Anda, klik Package.appxmanifest kanan dan pilih Buka dengan > Editor XML (Teks).
  4. <Dependencies> Temukan elemen dalam file. Tambahkan yang berikut ini, dan ganti [MainPackageDependency] dengan nama keluarga paket Anda dari Langkah 2. Ini akan menentukan bahwa paket opsional Anda tergantung pada paket utama Anda. 
    <uap3:MainPackageDependency Name="[MainPackageDependency]"/>

Catatan

Jika Anda ingin membuat paket opsional dari penerbit yang berbeda, Anda harus menentukan penerbit aplikasi utama jika berbeda. Seperti so <uap4:MainPackageDependency Name="Main_app" Publisher="CN=Contoso..." />. Ini tidak akan berfungsi jika Anda menerbitkan ke Penyimpanan.

Setelah Anda menyiapkan dependensi paket dari Langkah 1 hingga 4, Anda dapat terus mengembangkan seperti biasa. Untuk informasi selengkapnya, lihat Postingan blog: Membuat paket opsional pertama Anda.

Visual Studio dapat dikonfigurasi untuk menyebarkan kembali paket utama Setiap kali Anda menyebarkan paket opsional. Untuk mengatur dependensi build di Visual Studio, Anda harus:

  1. Klik kanan proyek paket opsional dan pilih Bangun > Dependensi Proyek...
  2. Periksa proyek paket utama dan pilih "OK".

Sekarang, setiap kali Anda memasukkan F5 atau membangun proyek paket opsional, Visual Studio akan membangun proyek paket utama terlebih dahulu. Ini akan memastikan bahwa proyek utama dan proyek opsional Anda sinkron.

Set terkait terdiri dari paket utama dan paket opsional yang digabungkan erat melalui metadata yang ditentukan dalam file .appxbundle atau .msixbundle dari paket utama. Metadata ini menautkan paket utama ke paket opsional (menggunakan nama file .appxbundle + versi), dan paket opsional ke paket utama (menggunakan nama independen versi). Visual Studio membantu Anda mendapatkan metadata yang benar dalam file Anda.

Penerapan versi paket dalam set terkait disinkronkan dengan cara yang tidak akan memungkinkan versi terbaru paket apa pun digunakan hingga semua paket set terkait (ditentukan oleh versi dalam paket utama) diinstal. Paket dilayankan secara independen, tetapi paket yang ditentukan dalam set mungkin tidak digunakan sampai semuanya diperbarui. Untuk informasi selengkapnya tentang set terkait, lihat Postingan blog: Alat untuk membuat set terkait.

Untuk mengonfigurasi solusi aplikasi Anda untuk set terkait, gunakan langkah-langkah berikut:

  1. Klik kanan proyek paket utama, pilih Tambahkan > Item Baru...
  2. Dari jendela, cari Templat yang Diinstal untuk ".txt" dan tambahkan file teks baru.

    Penting

    File teks baru harus diberi nama: Bundle.Mapping.txt.

  3. Bundle.Mapping.txt Dalam file masukkan string "[OptionalProjects]" diikuti dengan jalur relatif ke proyek paket opsional Anda. Berikut adalah contoh Bundle.Mapping.txt file: 
    [OptionalProjects]
"..\ActivatableOptionalPackage1\ActivatableOptionalPackage1.vcxproj"
"..\ActivatableOptionalPackage2\ActivatableOptionalPackage2.vcxproj"

Saat solusi Anda dikonfigurasi dengan cara ini, Visual Studio akan membuat manifes bundel bernama AppxBundleManifest.xml untuk paket utama dengan semua metadata yang diperlukan untuk set terkait.

Perhatikan bahwa seperti paket opsional, Bundle.Mapping.txt file untuk set terkait hanya akan berfungsi pada Windows 10, versi 1703 atau yang lebih tinggi. Selain itu, Versi Min Platform Target aplikasi Anda harus diatur ke 10.0.15063.0 atau yang lebih tinggi.

Menghapus Paket Opsional

Pengguna dapat masuk ke aplikasi Pengaturan mereka dan menghapus paket opsional. Demikian pula, pengembang dapat menggunakan RemoveOptionalPackageAsync untuk menghapus daftar paket opsional.

PackageCatalog catalog = PackageCatalog.OpenForCurrentPackage();
List<string> optionalList = new List<string>();
optionalList.Add("FabrikamAgeAnalysis_kwpnjs8c36mz0");
    
// Warn user that application will be restarted. 
var result = await catalog.RemoveOptionalPackagesAsync(optionalList);
if (result.ExtendedError != null)
{
    throw removalResult.ExtendedError;
}

Catatan

Dalam kasus set terkait, platform perlu memulai ulang aplikasi utama untuk menyelesaikan penghapusan untuk menghindari situasi di mana aplikasi memiliki konten yang dimuat dari paket yang sedang dihapus. Aplikasi harus memberi tahu pengguna bahwa aplikasi harus dimulai ulang sebelum aplikasi memanggil API.

Jika paket opsional hanya konten, pengembang harus secara eksplisit memberi tahu platform bahwa paket yang akan dihapus 'tidak digunakan' oleh aplikasi sebelum pengembang menghapus paket opsional. Ini juga memungkinkan pengembang untuk menghapus paket tanpa menghidupkan ulang.

Masalah yang diketahui

Men-debug proyek opsional set terkait saat ini tidak didukung di Visual Studio. Untuk mengatasi masalah ini, Anda dapat menyebarkan dan meluncurkan aktivasi (Ctrl + F5) dan melampirkan debugger secara manual ke proses. Untuk melampirkan debugger, buka menu "Debug" di Visual Studio, pilih "Lampirkan ke Proses...", dan lampirkan debugger ke proses aplikasi utama.