SDK Aplikasi Windows panduan penyebaran untuk aplikasi paket yang bergantung pada kerangka kerja

Artikel ini menyediakan panduan tentang menyebarkan aplikasi paket yang bergantung pada kerangka kerja (lihat Apa itu MSIX?) yang menggunakan SDK Aplikasi Windows. Topik yang setara untuk opsi pengemasan yang bergantung pada kerangka kerja lainnya adalah SDK Aplikasi Windows panduan penyebaran untuk aplikasi yang bergantung pada kerangka kerja yang dikemas dengan lokasi eksternal atau tidak dikemas.

Overview

Secara default, saat Anda membuat proyek menggunakan salah satu templat WinUI 3 di Visual Studio, proyek Anda dikonfigurasi untuk membangun aplikasi ke dalam paket MSIX menggunakan MSIX proyek tunggal (lihat Mengemas aplikasi Anda menggunakan MSIX proyek tunggal) atau proyek Windows Application Packaging (lihat Menyiapkan aplikasi desktop Anda untuk kemasan MSIX di Visual Studio). Anda kemudian dapat membuat paket MSIX untuk aplikasi Anda dengan menggunakan instruksi di Package desktop atau aplikasi UWP di Visual Studio. Setelah Anda membuat paket MSIX untuk aplikasi Anda, Anda memiliki beberapa opsi untuk Mengelola penyebaran MSIX.

Untuk mempelajari lebih lanjut tentang paket yang mungkin diperlukan oleh aplikasi paket Anda saat menggunakan SDK Aplikasi Windows, lihat arsitektur deployment untuk SDK Aplikasi Windows. Itu termasuk paket Framework, Main, dan Singleton ; yang semuanya ditandatangani dan diterbitkan oleh Microsoft. Ada dua persyaratan utama untuk menyebarkan aplikasi paket:

  1. Deploy paket kerangka kerja SDK Aplikasi Windows.
  2. Panggil API Penggelaran.

Prerequisites

Menyebarkan paket kerangka kerja SDK Aplikasi Windows

Paket kerangka kerja SDK Aplikasi Windows berisi biner SDK Aplikasi Windows yang digunakan pada waktu proses, dan diinstal dengan aplikasi Anda. Kerangka kerja ini memiliki persyaratan penyebaran yang berbeda untuk berbagai saluran SDK Aplikasi Windows.

Versi stabil

Saat Anda menginstal versi rilis stabil dari paket SDK Aplikasi Windows NuGet di komputer pengembangan Anda, dan Anda membuat proyek menggunakan salah satu templat proyek WinUI yang disediakan, manifes paket yang dihasilkan berisi elemen PackageDependency yang menentukan dependensi pada paket kerangka kerja.

Namun, jika Anda membuat paket aplikasi secara manual menggunakan Proyek Pengemasan Aplikasi Windows terpisah, maka Anda harus mendeklarasikan PackageReference dalam file /> 

<ItemGroup>
   <PackageReference Include="Microsoft.WindowsAppSDK" Version="1.8.260209005">
       <IncludeAssets>build</IncludeAssets>
   </PackageReference>
</ItemGroup>

Dependensi paket tersebut memastikan bahwa paket Kerangka Kerja diinstal saat aplikasi Anda disebarkan ke komputer lain.

Versi pratinjau

Saat Anda menginstal versi rilis pratinjau paket SDK Aplikasi Windows NuGet di komputer pengembangan Anda, versi pratinjau paket kerangka kerja SDK Aplikasi Windows disebarkan selama waktu build sebagai dependensi paket NuGet.

Memanggil API Penyebaran

Lihat juga Initialize SDK Aplikasi Windows.

API Penyebaran disediakan oleh paket kerangka kerja SDK Aplikasi Windows, dan tersedia di Microsoft.Windows. ApplicationModel.WindowsAppRuntime namespace. Model aplikasi Windows tidak mendukung mendeklarasikan dependensi pada paket Utama dan Singleton. Oleh karena itu, API Penyebaran diperlukan karena alasan ini:

  1. Untuk menyebarkan paket Singleton untuk fitur yang tidak ada dalam paket Kerangka Kerja (misalnya, pemberitahuan push).
  2. Untuk menyebarkan paket Utama, yang memungkinkan pembaruan otomatis ke paket Kerangka Kerja dari Microsoft Store.

Untuk aplikasi paket yang tidak didistribusikan melalui Store, Anda sebagai pengembang bertanggung jawab untuk mendistribusikan paket Framework. Kami menyarankan agar Anda memanggil API Penyebaran sehingga setiap pembaruan layanan penting dikirimkan. Perhatikan bahwa untuk menggunakan fitur di luar paket Kerangka Kerja (misalnya, pemberitahuan push), paket Singleton harus disebarkan (ini dapat dilakukan dengan API Penyebaran, atau dengan mendistribusikan ulang paket MSIX menggunakan metode penginstalan Anda sendiri).

Important

Hanya aplikasi paket yang memiliki kepercayaan penuh atau yang memiliki kemampuan terbatas packageManagement yang memiliki izin untuk menggunakan API Distribusi untuk menginstal dependensi paket Main dan Singleton.

Anda harus memanggil API Penyebaran setelah proses aplikasi Anda diinisialisasi, tetapi sebelum aplikasi Anda menggunakan fitur runtime SDK Aplikasi Windows yang menggunakan paket Singleton (misalnya, pemberitahuan push). Metode utama API Penyebaran adalah metode GetStatus statis dan Inisialisasi kelas DeploymentManager .

  • Metode GetStatus mengembalikan status penyebaran runtime SDK Aplikasi Windows yang sedang dimuat. Gunakan metode ini untuk mengidentifikasi apakah ada pekerjaan yang diperlukan untuk menginstal paket runtime SDK Aplikasi Windows sebelum aplikasi saat ini dapat menggunakan fitur SDK Aplikasi Windows.
  • Metode Initialize memverifikasi apakah semua paket yang diperlukan ada dalam versi minimum yang dibutuhkan oleh runtime SDK Aplikasi Windows yang sedang dimuat saat ini. Jika ada dependensi paket yang hilang, maka metode ini mencoba mendaftarkan paket yang hilang tersebut. Dimulai pada SDK Aplikasi Windows 1.1, metode Initialize juga mendukung opsi untuk menyebarkan paksa paket runtime SDK Aplikasi Windows. Itu mematikan proses apa pun untuk paket runtime Main dan Singleton , dan dengan demikian mengganggu layanan mereka (misalnya, pemberitahuan push tidak akan mengirimkan pemberitahuan selama waktu ini). Anda harus memanggil Inisialisasi hanya sekali. Anda tidak perlu memanggil Initialize untuk aplikasi yang disebarkan melalui perintah Start Tanpa Debugging dan Mulai Debugging di Visual Studio.

Important

Nilai default properti Visual Studio <WindowsAppSdkDeploymentManagerInitialize> adalah true. Jadi jika Anda ingin memanggil DeploymentManager.Initialize secara eksplisit, lalu atur <WindowsAppSdkDeploymentManagerInitialize>false</WindowsAppSdkDeploymentManagerInitialize> dalam file proyek Visual Studio Anda.

Aplikasi sampel API penerapan

Untuk panduan tambahan tentang cara menggunakan metode GetStatus dan Initialize kelas DeploymentManager , jelajahi aplikasi sampel yang tersedia.

Jelajahi aplikasi sampel API Penyebaran

Mengatasi kesalahan penginstalan

Jika API Penyebaran mengalami kesalahan selama penginstalan paket runtime SDK Aplikasi Windows, api tersebut mengembalikan kode kesalahan yang menjelaskan masalahnya.

Tabel berikut mencantumkan kode kesalahan umum dari API Penyebaran dan penyebab umumnya:

Kode kesalahan Name Penyebab umum
0x80070005 ACCESS_DENIED Aplikasi ini tidak memiliki kepercayaan penuh, atau tidak memiliki kapabilitas terbatas packageManagement. Jalankan yang ditingkatkan atau tambahkan kemampuan yang diperlukan.
0x80073CF0 ERROR_INSTALL_OPEN_PACKAGE_FAILED Paket MSIX rusak atau tidak dapat diakses. Pastikan file paket utuh dan jalurnya benar.
0x80073CF3 ERROR_INSTALL_PREREQUISITE_FAILED Paket dependensi yang diperlukan hilang atau tidak kompatibel. Pastikan paket kerangka kerja VCLibs dan prasyarat lainnya diinstal.
0x80073D06 ERROR_PACKAGES_IN_USE (kesalahan: paket sedang digunakan) Satu atau beberapa paket sedang digunakan dan tidak dapat diperbarui. Tutup semua aplikasi menggunakan runtime SDK Aplikasi Windows, lalu coba lagi.
0x80073CFB ERROR_PACKAGE_ALREADY_EXISTS Versi paket sudah terdaftar. Ini hanya informasi—Anda dapat terus menggunakan aplikasi.
0x80073CF9 ERROR_INSTALL_FAILED Kegagalan penginstalan umum. Periksa log peristiwa untuk detail selengkapnya (lihat di bawah).

Petunjuk / Saran

Untuk daftar lengkap kode kesalahan penginstalan paket MSIX, lihat Pemecahan masalah pengemasan, penyebaran, dan kueri aplikasi Windows.

Jika kode kesalahan tidak memberikan informasi yang cukup, maka Anda dapat menemukan informasi diagnostik lebih lanjut di log peristiwa terperinci (lihat Mendapatkan informasi diagnostik). Log peristiwa terletak di Pemantau Peristiwa di bawah Log Aplikasi dan Layanan>Microsoft>Windows>AppxDeployment-Server.

Jika Anda mengalami kesalahan yang tidak dapat Anda diagnosis, maka ajukan masalah di WindowsAppSDK GitHub repo dengan kode kesalahan dan log peristiwa sehingga kami dapat menyelidiki masalah tersebut.

  • Last updated on