Panduan pemecahan masalah MSIX

Panduan ini mencakup kesalahan MSIX yang paling umum di seluruh penginstalan, penandatanganan, pengiriman App Installer, dependensi yang hilang, dan perilaku runtime. Setiap bagian mencakup gejala, akar penyebab, dan resolusi.

Untuk log lengkap peristiwa penyebaran, buka Pemantau Peristiwa dan navigasikan ke: Log Aplikasi dan Layanan → Microsoft → Windows → AppxDeployment-Server → Operasional

Petunjuk / Saran

Untuk serangkaian diagnostik terkonsolidasi, jalankan juga Windows App Certification Kit sebelum mendistribusikan paket Anda.

Kesalahan penginstalan

0x80070005 — Akses ditolak

Gejala: Add-AppxPackage atau Penginstal Aplikasi gagal dengan kode 0x80070005kesalahan .

Aplikasi ke: Windows 10 dan yang lebih baru, Windows 11

Penyebab dan perbaikan:

Penyebab Perbaiki
Berjalan sebagai pengguna standar tanpa elevasi ketika paket memerlukan penginstalan per mesin Jalankan PowerShell sebagai Administrator. Untuk menginstal untuk semua pengguna, gunakan Add-AppxProvisionedPackage alih-alih Add-AppxPackage.
Perangkat lunak antivirus atau keamanan memblokir file paket Nonaktifkan pemindaian real-time untuk sementara waktu, atau tambahkan pengecualian untuk .msix / .msixbundle file
Paket telah disiapkan untuk pengguna lain dan belum tersedia. Gunakan Add-AppxProvisionedPackage untuk menyediakan semua pengguna
ACL sistem berkas memblokir akses baca terhadap paket Periksa izin pada file paket dengan icacls; berikan akses baca ke pengguna penginstalan

Penginstalan paket diblokir karena aplikasi sedang digunakan

Gejala: Pembaruan atau penginstalan ulang gagal dengan kesalahan yang menunjukkan paket sedang digunakan. Dalam Pemantau Peristiwa, Anda melihat bahwa operasi penyebaran ditolak.

Aplikasi ke: Windows 10 dan yang lebih baru, Windows 11

Perbaikan: Tutup semua instans aplikasi yang sedang berjalan sebelum memperbarui. Jika aplikasi adalah layanan latar belakang atau memiliki tugas latar belakang yang terdaftar, Anda mungkin perlu mengakhirinya juga:

Get-Process -Name "MyApp" | Stop-Process -Force
Add-AppxPackage -Path .\updated-app.msix

Untuk penyebaran perusahaan, pertimbangkan untuk menjadwalkan pembaruan selama waktu pemeliharaan menggunakan Intune atau Configuration Manager.

MinVersion atau ketidakcocokan arsitektur

Symptom: Penginstalan gagal dengan kesalahan seperti "Paket tidak dapat diinstal karena tidak kompatibel dengan versi Windows ini" atau "Paket tidak berlaku untuk komputer ini."

Aplikasi untuk: Windows 10 dan yang lebih baru

Penyebab dan perbaikan:

Penyebab Perbaiki
Paket MinVersion dalam manifes lebih tinggi dari versi OS Buat paket terpisah yang menargetkan versi OS yang diinstal, atau perbarui perangkat
Ketidakcocokan arsitektur (misalnya, paket arm64 pada perangkat x64) Membangun dan mendistribusikan varian arsitektur yang benar; gunakan bundel (.msixbundle) untuk melayani beberapa arsitektur dari satu file
Paket menargetkan API Windows 11-saja tanpa pemeriksaan kompatibilitas Tambahkan entri TargetDeviceFamily untuk Windows 10 dan Windows 11, atau jaga panggilan API dengan pemeriksaan versi saat runtime

Nota

Gunakan .msixbundle file saat mendistribusikan ke lingkungan arsitektur campuran. Bundel berisi paket untuk beberapa arsitektur dan Windows memilih yang benar pada waktu penginstalan.

Add-AppxPackage berhasil tetapi aplikasi hilang dari Menu Mulai

Gejala: PowerShell melaporkan keberhasilan, tetapi aplikasi tidak muncul di Menu Mulai atau daftar aplikasi.

Aplikasi ke: Windows 10 dan yang lebih baru, Windows 11

Penyebab umum:

  • Penginstalan per pengguna vs. per mesin: Add-AppxPackage hanya diinstal untuk pengguna saat ini. Jika Anda menjalankan sebagai Administrator tetapi mengharapkan aplikasi untuk pengguna lain, gunakan Add-AppxProvisionedPackage sebagai gantinya.
  • Paket terdaftar tetapi petak peta tidak disematkan: Aplikasi diinstal tetapi Menu Mulai belum disegarkan. Keluar dan masuk kembali, atau periksa Pengaturan → Aplikasi untuk mengonfirmasi penginstalan.
  • Entri Menu Mulai hilang dalam manifes: Verifikasilah bahwa elemen <Application> di AppxManifest.xml menyertakan entri VisualElements dengan Square150x150Logo yang valid.
  • Konflik nama keluarga paket duplikat: Jika versi aplikasi yang lebih baru atau lebih lama sudah diinstal dengan nama keluarga paket yang sama, penginstalan baru dapat menggantinya secara diam-diam. Periksa dengan Get-AppxPackage -Name "YourPackageFamilyName".

Kesalahan penandatanganan dan sertifikat

Nota

Untuk kode dan bendera kesalahan SignTool terperinci, lihat Masalah umum dan pemecahan masalah untuk SignTool.

Sertifikat tidak tepercaya (0x800B0109)

Gejala: Penginstalan gagal dengan kesalahan 0x800B0109 — "Rantai sertifikat diproses, tetapi dihentikan dalam sertifikat akar yang tidak dipercaya oleh penyedia kepercayaan."

Aplikasi ke: Windows 10 dan yang lebih baru, Windows 11

Penyebab: Sertifikat yang digunakan untuk menandatangani paket tidak ada di penyimpanan sertifikat tepercaya perangkat. Ini umum terjadi saat menggunakan sertifikat yang ditandatangani sendiri untuk pengembangan.

Perbaikan: Impor sertifikat penandatanganan ke penyimpanan Komputer Lokal → Orang Tepercaya perangkat (bukan penyimpanan pengguna saat ini — Penginstal Aplikasi hanya memeriksa penyimpanan mesin):

# Export the certificate from the package first (if needed)
$cert = (Get-AuthenticodeSignature -FilePath .\app.msix).SignerCertificate
Export-Certificate -Cert $cert -FilePath .\app-cert.cer

# Import into Trusted People (requires administrator rights)
Import-Certificate -FilePath .\app-cert.cer -CertStoreLocation Cert:\LocalMachine\TrustedPeople

Penting

Jangan impor sertifikat penandatanganan ke penyimpanan Otoritas Sertifikasi Akar Tepercaya kecuali sertifikat tersebut adalah CA akar. Mengimpor sertifikat self-signed yang tidak tepercaya di sana memperlemah keamanan perangkat.

Untuk aplikasi produksi, gunakan sertifikat yang dikeluarkan oleh CA tepercaya atau Azure Artifact Signing (sebelumnya Trusted Signing), yang terhubung ke Otoritas Sertifikat Root Verifikasi Identitas Microsoft — yang secara default dipercaya pada Windows 10 versi 1809 dan yang lebih baru, serta Windows 11.

ketidakcocokan nama Publisher (0x8007000B, ID Peristiwa 150)

Symptom: SignTool gagal dengan 0x8007000B, dan Pemantau Peristiwa (log operasional AppxPackagingOM) menunjukkan Event ID 150:

error 0x8007000B: The app manifest publisher name (CN=Contoso) must match
the subject name of the signing certificate (CN=Contoso, C=US).

Aplikasi ke: Windows 10 dan yang lebih baru, Windows 11

Cause: Atribut Publisher di AppxManifest.xml harus sama persis dengan nama subject sertifikat penandatanganan — termasuk semua bidang nama khusus dalam urutan yang sama.

Perbaikan:

  1. Dapatkan nama subjek yang tepat dari sertifikat:

    (Get-Item Cert:\CurrentUser\My\THUMBPRINT).Subject
# Example output: CN=Contoso, C=US

  2. Perbarui AppxManifest.xml agar cocok persis:

    <Identity Name="Contoso.MyApp"
          Publisher="CN=Contoso, C=US"
          ... />

  3. Kemas ulang dengan MakeAppx.exe dan tandatangani ulang.

Petunjuk / Saran

Saat menggunakan Azure Artifact Signing (sebelumnya Penandatanganan yang Tepercaya), nilai penerbit dalam manifes Anda harus cocok dengan identitas terverifikasi Anda — ditemukan di portal Azure di bawah bidang Nama Subjek pada profil sertifikat Anda.

Penginstal Aplikasi dan Kesalahan Pengiriman Web

Ketidakcocokan versi skema dalam file .appinstaller

Gejala: Penginstal Aplikasi gagal mengurai atau memproses .appinstaller file, sering kali dengan kesalahan umum tentang file yang tidak valid atau skema yang tidak didukung.

Aplikasi ke: Windows 10 dan yang lebih baru (tergantung versi — lihat tabel)

Cause: Atribut Uri dari elemen akar <AppInstaller> menentukan versi skema yang tidak didukung versi Windows yang diinstal.

Versi schema berdasarkan rilis Windows:

versi Windows Versi skema minimum yang didukung
Windows 10 versi 1709 1.0.0.0
Windows 10 versi 1803 1.1.0.0
Windows 10 versi 1809 1.2.0.0
Windows 10 versi 1903 dan yang lebih baru, Windows 11 1.3.0.0, 1.4.0.0, 1.5.0.0

Perbaiki: Atur URI skema di file Anda .appinstaller ke versi minimum yang diperlukan oleh OS paling rendah yang Anda dukung:

<?xml version="1.0" encoding="utf-8"?>
<AppInstaller Uri="https://example.com/app.appinstaller"
              Version="1.0.0.0"
              xmlns="http://schemas.microsoft.com/appx/appinstaller/2017">

Hindari menggunakan versi skema terbaru jika Anda perlu mendukung versi Windows 10 yang lebih lama.

File dilayani dengan jenis MIME yang salah atau Panjang Konten yang hilang

Gejala: Penginstal Aplikasi gagal saat menginstal dari titik akhir HTTP/HTTPS. Kesalahan mungkin umum, seperti 0x80072F76 ("Kesalahan tidak diketahui") atau "Penginstalan aplikasi gagal."

Aplikasi untuk: Windows 10 dan yang lebih baru

Penyebab: Server web melayani .msixfile , , .msixbundleatau .appinstaller dengan header yang salah Content-Type , atau menghilangkan Content-Length header.

Perbaikan: Konfigurasikan server web Anda untuk melayani file terkait MSIX dengan jenis MIME yang benar:

Ekstensi berkas Jenis MIME yang diperlukan
.msix application/msix
.msixbundle application/msixbundle
.appinstaller application/appinstaller
.appx application/appx
.appxbundle application/appxbundle

Pastikan juga setiap respons menyertakan header yang valid Content-Length — ini berlaku untuk permintaan GET dan HEAD.

Untuk IIS, tambahkan pemetaan jenis MIME di web.config. Untuk halaman Azure Static Web Apps atau GitHub, jenis MIME untuk ekstensi ini mungkin memerlukan konfigurasi eksplisit atau solusi hosting kustom.

Dependensi hilang

Paket kerangka kerja tidak diinstal (VCLibs, .NET, SDK Aplikasi Windows)

Symptom: Aplikasi berhasil diinstal tetapi crash saat peluncuran, atau penginstalan gagal dengan kesalahan dependensi yang merujuk nama keluarga paket seperti Microsoft.VCLibs, Microsoft.WindowsAppRuntime, atau Microsoft.NET.Native.

Aplikasi ke: Windows 10 dan yang lebih baru, Windows 11

Kerangka kerja umum dan tempat mendapatkannya:

Kerangka kerja Diperlukan ketika Sumber
VCLibs (x64/x86/arm64) Aplikasi menggunakan runtime C++ Microsoft Store (terpasang secara otomatis) atau unduhan langsung
.NET 8 Desktop Runtime Aplikasi menargetkan .NET 8 Disertakan dengan SDK Aplikasi Windows; atau unduhan langsung
SDK Aplikasi Windows (WinAppSDK) Aplikasi menggunakan WinUI 3 atau API WinAppSDK lainnya SDK Aplikasi Windows dirilis di GitHub

Perbaikan untuk pengembangan: Saat menginstal melalui Add-AppxPackage secara lokal, tambahkan -DependencyPackages parameter atau instal paket kerangka kerja terlebih dahulu:

# Install VCLibs dependency first
Add-AppxPackage -Path .\Microsoft.VCLibs.x64.14.00.Desktop.appx

# Then install your app
Add-AppxPackage -Path .\MyApp.msix

Perbaikan untuk distribusi: Jika mendistribusikan di luar Toko, sertakan paket kerangka kerja dalam file Anda .appinstaller di bawah <Dependencies>:

<Dependencies>
  <Package Name="Microsoft.VCLibs.140.00.UWPDesktop"
           Publisher="CN=Microsoft Corporation, O=Microsoft Corporation, L=Redmond, S=Washington, C=US"
           Version="14.0.30704.0"
           Uri="https://aka.ms/Microsoft.VCLibs.x64.14.00.Desktop.appx"
           ProcessorArchitecture="x64"/>
</Dependencies>

Nota

Saat mendistribusikan melalui Microsoft Store, dependensi kerangka kerja diunduh dan diinstal secara otomatis. Manajemen dependensi manual hanya diperlukan untuk sideloading dan penyebaran perusahaan.

SignTool tidak ditemukan di CI/CD

Symptom: Alur CI/CD (GitHub Actions, Azure DevOps) gagal dengan kesalahan seperti 'signtool' is not recognized as an internal or external command atau SignTool.exe: not found.

Berlaku untuk: Windows 10 dan yang lebih baru, Windows 11 (perangkat penandatanganan)

Cause: SignTool adalah bagian dari SDK Windows dan tidak termasuk dalam gambar pelari CI standar secara default.

Fixes:

Opsi 1 — Instalasi SDK Windows di alur kerja (GitHub Actions):

- name: Install Windows SDK
  run: |
    winget install --id Microsoft.WindowsSDK.10.0.22621 --accept-source-agreements --accept-package-agreements

Opsi 2 — Gunakan WinApp CLI (paling sederhana untuk penandatanganan MSIX):

- name: Install WinApp CLI
  run: winget install -e --id Microsoft.WinAppCLI --source winget --accept-source-agreements
- name: Sign MSIX
  run: winapp sign output\MyApp.msix --cert ${{ secrets.CERT_THUMBPRINT }}

Option 3 — Gunakan Penandatanganan Artefak Azure (disarankan untuk produksi):

- name: Sign with Azure Artifact Signing
  uses: azure/trusted-signing-action@v0
  with:
    azure-tenant-id: ${{ secrets.AZURE_TENANT_ID }}
    azure-client-id: ${{ secrets.AZURE_CLIENT_ID }}
    azure-client-secret: ${{ secrets.AZURE_CLIENT_SECRET }}
    endpoint: ${{ secrets.AZURE_ARTIFACT_SIGNING_ENDPOINT }}
    trusted-signing-account-name: ${{ secrets.AZURE_CODE_SIGNING_NAME }}
    certificate-profile-name: ${{ secrets.AZURE_CERT_PROFILE_NAME }}
    files-folder: ${{ github.workspace }}\output
    files-folder-filter: msix

Nota

Tindakan GitHub diberi nama azure/trusted-signing-action (nama layanan sebelumnya). Ini adalah tindakan resmi terlepas dari proses penggantian merek menjadi Penandatanganan Artefak.

Untuk panduan lengkap mengenai proses penandatanganan CI/CD, lihat Menandatangani paket MSIX Anda - panduan menyeluruh.

Perilaku runtime dan virtualisasi

Paket MSIX berjalan di dalam kontainer aplikasi ringan. Beberapa perilaku yang tampaknya bug sebenarnya berdasarkan desain - kontainer mencegat file dan operasi registri untuk melindungi sistem lainnya.

Mengapa penulisan berkas tampaknya menghilang (pengalihan berkas VFS)

Gejala: Aplikasi menulis file ke jalur seperti C:\Program Files\MyApp\config.ini pada runtime, tetapi file tidak muncul di sana. Aplikasi membaca kembali nilai dengan benar, tetapi proses atau pengguna lain tidak melihatnya.

Aplikasi ke: Windows 10 dan yang lebih baru, Windows 11

Penjelasan: MSIX menggunakan pengalihan Virtual File System (VFS ). Penulisan ke jalur sistem yang dilindungi dialihkan secara diam-diam ke kontainer per pengguna:

%LocalAppData%\Packages\<PackageFamilyName>\LocalCache\Local\VFS\

Ini telah dirancang untuk mencegah aplikasi MSIX memodifikasi lokasi sistem bersama dan mendukung penghapusan instalasi yang bersih.

Opsi:

  • Gunakan folder data aplikasi sebagai gantinya: Tulis ke ApplicationData.Current.LocalFolder (WinRT) atau %LocalAppData%\Packages\<PFN>\LocalState\ untuk data per pengguna yang harus bertahan.
  • Gunakan AppData\Roaming untuk data yang harus berpindah di seluruh perangkat.
  • Periksa kontainer VFS untuk melihat file yang dialihkan: %LocalAppData%\Packages\<PackageFamilyName>\LocalCache\

Untuk detail selengkapnya tentang jalur apa yang divirtualisasi, lihat Memecahkan masalah runtime dalam kontainer MSIX.

Mengapa penulisan registri tampaknya menghilang (virtualisasi registri)

Gejala: Aplikasi menulis ke HKEY_LOCAL_MACHINE\Software\MyApp\ pada runtime, tetapi nilainya tidak terlihat oleh proses lain atau bertahan dari penginstaian ulang.

Aplikasi ke: Windows 10 dan yang lebih baru, Windows 11

Penjelasan: MSIX mencegat penulisan ke HKLM\Software dan mengalihkannya ke sarang registri per paket yang diisolasi dari sistem lainnya. Pada penghapusan instalan, sarang dihapus.

Opsi:

  • Tulis pengaturan per pengguna ke HKEY_CURRENT_USER\Software\<AppName> — ini tidak divirtualisasi dan tetap ada.
  • Gunakan API Windows ApplicationData untuk penyimpanan pengaturan terstruktur.
  • Deklarasikan entri registri yang harus dibagikan antar pengguna atau proses dalam AppxManifest.xml dengan menggunakan mekanisme <Extensions> / <com:Extension>.

Untuk melihat perilaku kontainer MSIX yang lebih dalam, lihat Menjabarkan cara aplikasi desktop kemasan berjalan pada Windows.

Batasan MSIX di Windows 10

Beberapa fitur MSIX memerlukan Windows 11 atau versi Windows 10 tertentu. Jika Anda menyebarkan ke perangkat Windows 10, ketahui hal berikut.

Fitur yang memerlukan Windows 10, versi 2004 (build 19041) atau yang lebih baru

Feature Versi minimum
Skema pembaruan otomatis 2021 (ShowPrompt, UpdateBlocksActivation) Windows 10 2004 (19041)
Penegakan integritas paket (uap10:PackageIntegrity) Windows 10 2004 (19041)
Perbaikan otomatis untuk Penginstal Aplikasi Windows 10 2004 (19041)
Tidak ada sakelar kebijakan sideloading terpisah untuk instalasi paket aplikasi tepercaya; lihat Mengaktifkan perangkat Anda untuk pengembangan untuk persyaratan saat ini Windows 10 2004 (19041)

Fitur yang memerlukan Windows 11

Feature Catatan
Identitas paket jarang tanpa kemasan penuh Memerlukan Windows 11
Dukungan MSIX untuk aplikasi yang tidak dikemas dengan lokasi eksternal (dukungan platform penuh) Beberapa API ditingkatkan dalam Windows 11
Performa penginstalan MSIX per mesin yang ditingkatkan pengoptimalan Windows 11

Perangkat Windows 10 yang lebih lama dari versi 1709

MSIX tidak didukung secara asli pada versi Windows 10 sebelum 1709 (Fall Creators Update). Untuk menyebarkan paket MSIX ke perangkat tersebut, gunakan MSIX Core, yang menyediakan lapisan kompatibilitas untuk versi Windows 10 tingkat bawah.

Ekstensi manifes

Beberapa ekstensi namespace AppxManifest.xml hanya tersedia di Windows 11. Mendeklarasikannya pada paket yang menargetkan Windows 10 mungkin gagal dalam validasi skema selama pengemasan atau ditolak selama penginstalan. Periksa referensi skema manifes paket aplikasi untuk MinOSVersion yang terdaftar bagi setiap ekstensi.

Tips penelusuran kesalahan

Untuk memverifikasi fitur MSIX apa yang tersedia pada build Windows 10 tertentu, periksa fitur MSIX dan platform yang didukung halaman, yang mencantumkan ketersediaan fitur menurut versi OS.

  • Last updated on