MSIX sorun giderme kılavuzu

Bu kılavuz, yükleme, imzalama, Uygulama Yükleyicisi teslimi, eksik bağımlılıklar ve çalışma zamanı davranışı genelinde en yaygın MSIX hatalarını kapsar. Her bölümde belirti, kök neden ve çözüm bulunur.

Dağıtım olaylarının tam günlüğü için Olay Görüntüleyicisi açın ve adresine gidin: Applications ve Services Logs → Microsoft → Windows → AppxDeployment-Server → Operational

Tavsiye

Birleştirilmiş bir tanılama kümesi için paketinizi dağıtmadan önce Windows Uygulaması Certification Kit komutunu da çalıştırın.

Yükleme hataları

0x80070005 — Erişim reddedildi

Belirti: Add-AppxPackage veya Uygulama Yükleyicisi hata koduyla 0x80070005başarısız oluyor.

Applies to: Windows 10 ve üzeri, Windows 11

Nedenler ve düzeltmeler:

Nedeni Düzelt
Paket makine başına yükleme gerektirdiğinde yükseltme olmadan standart kullanıcı olarak çalıştırma PowerShell'i Yönetici olarak çalıştırın. Tüm kullanıcılar için yükleme yapmak amacıyla Add-AppxPackage yerine Add-AppxProvisionedPackage kullanın.
Paket dosyasını engelleyen virüsten koruma veya güvenlik yazılımı Gerçek zamanlı taramayı geçici olarak devre dışı bırakın veya dosya için .msix / .msixbundle bir dışlama ekleyin
Başka bir kullanıcı için hazırlanmış ve sağlanmamış paket "Add-AppxProvisionedPackage ile tüm kullanıcılara hizmet sağlamak için kullanın"
Dosya sistemi ACL'leri pakete okuma erişimini engelliyor ile icaclspaket dosyasındaki izinleri denetleyin; yükleme kullanıcısına okuma erişimi verin

Uygulama kullanımda olduğundan paket yüklemesi engellendi

Belirti: Güncelleştirme veya yeniden yükleme, paketin kullanımda olduğunu belirten bir hatayla başarısız oluyor. Olay Görüntüleyicisi dağıtım işleminin reddedildiğini görürsünüz.

Applies to: Windows 10 ve üzeri, Windows 11

Düzeltme: Güncelleştirmeden önce uygulamanın çalışan tüm örneklerini kapatın. Uygulama bir arka plan hizmetiyse veya kayıtlı bir arka plan görevi varsa, bunları da sonlandırmanız gerekebilir:

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

Kurumsal dağıtımlar için, Intune veya Yapılandırma Yöneticisi kullanarak bakım pencereleri sırasında güncelleştirmeleri zamanlamayı göz önünde bulundurun.

MinVersion veya mimarisi uyumsuzluğu

Symptom: Yükleme "Paket bu Windows sürümüyle uyumlu olmadığından yüklenemedi" veya "Paket bu makine için geçerli değil" gibi bir hatayla başarısız oluyor.

Geçerlidir: Windows 10 ve üzeri

Nedenler ve düzeltmeler:

Nedeni Düzelt
Bildirimdeki paket MinVersion işletim sistemi sürümünden daha yüksek Yüklü işletim sistemi sürümünü hedefleyen ayrı bir paket oluşturun veya cihazı güncelleştirin
Mimari uyuşmazlığı (örneğin, x64 cihazında arm64 paketi) Doğru mimari değişkenini oluşturma ve dağıtma; bir dosyadan birden çok mimariye hizmet vermek için paket (.msixbundle) kullanma
Paket, uyumluluk denetimi olmadan yalnızca Windows 11 API'yi hedefler Hem Windows 10 hem de Windows 11 için TargetDeviceFamily girişi ekleyin veya API çağrısını çalışma zamanında bir sürüm denetimiyle koruma

Uyarı

Karma mimari ortamlarına dağıtırken .msixbundle dosyalarını kullanın. Paket birden çok mimariye yönelik paketler içerir ve Windows yükleme zamanında doğru olanı seçer.

Add-AppxPackage başarılı oluyor ancak Başlat Menüsünde uygulama eksik

Belirti: PowerShell başarılı olduğunu bildirir, ancak uygulama Başlat Menüsünde veya uygulama listesinde görünmez.

Applies to: Windows 10 ve üzeri, Windows 11

Yaygın nedenler:

  • Kullanıcı başına ve makine başına yükleme: Add-AppxPackage yalnızca geçerli kullanıcı için yüklenir. Yönetici olarak çalışıyor ancak uygulamayı başka bir kullanıcı için bekliyorsanız, bunun yerine kullanın Add-AppxProvisionedPackage .
  • Paket kaydedildi ancak kutucuk sabitlenmedi: Uygulama yüklü ancak Başlat Menüsü yenilenmedi. Oturumu kapatın ve yeniden oturum açın veya yüklemeyi onaylamak için Ayarlar → Uygulamalar'ı işaretleyin.
  • Bildirimde Başlat Menüsü girdisi eksik: içindeki <Application> öğesinin AppxManifest.xml geçerli VisualElementsbir Square150x150Logo giriş içerdiğini doğrulayın.
  • Yinelenen paket ailesi adı çakışması: Uygulamanın daha yeni veya daha eski bir sürümü aynı paket ailesi adıyla zaten yüklüyse, yeni yükleme sessizce yerini alabilir. ile Get-AppxPackage -Name "YourPackageFamilyName"denetleyin.

İmzalama ve sertifika hataları

Uyarı

Ayrıntılı SignTool hata kodları ve bayrakları için bkz. SignTool için bilinen sorunlar ve sorun giderme.

Sertifika güvenilir değil (0x800B0109)

Belirti: Yükleme şu hatayla 0x800B0109 başarısız oluyor: "Sertifika zinciri işlendi, ancak güven sağlayıcısı tarafından güvenilmeyen bir kök sertifikada sonlandırıldı."

Applies to: Windows 10 ve üzeri, Windows 11

Neden: Paketi imzalamak için kullanılan sertifika, cihazın güvenilen sertifika depolarında değil. Geliştirme için otomatik olarak imzalanan sertifikalar kullanılırken bu yaygın bir durumdur.

Düzeltme: İmzalama sertifikasını cihazın Yerel Bilgisayar → Güvenilen Kişiler deposuna aktarın (geçerli kullanıcı deposu değil— Uygulama Yükleyicisi yalnızca makine depoyu denetler):

# 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

Önemli

Sertifika bir kök CA olmadığı sürece, imzalama sertifikalarını Güvenilen Kök Sertifika Yetkilileri deposuna aktarmayın. Güvenilmeyen kendi kendine imzalanmış sertifikaları içeri aktarmak cihazın güvenlik duruşunu zayıflatır.

Üretim uygulamaları için, güvenilir bir CA veya Azure Yapıt İmzalama (eski adıyla Güvenilen İmzalama) tarafından verilen ve Microsoft Kimlik Doğrulama Kök Sertifika Yetkilisine zincirlenen bir sertifika kullanın; bu sertifika varsayılan olarak Windows 10 sürüm 1809 ve sonraki sürümlerde güvenilirdir, Windows 11.

Yayıncı adı uyuşmazlığı (0x8007000B, Olay Kimliği 150)

Symptom: SignTool 0x8007000B ile başarısız oluyor ve Olay Görüntüleyicisi (AppxPackagingOM işlem günlüğü) Event ID 150 gösteriyor:

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

Applies to: Windows 10 ve üzeri, Windows 11

Cause: Publisher içindeki AppxManifest.xml özelliği, imza sertifikasının subject adı ile tam olarak eşleşmelidir; tüm ayırt edici ad alanları aynı sırada olacak şekilde gereklidir.

Düzeltme:

  1. Sertifikadan tam konu adını alın:

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

  2. Tam olarak eşleşecek şekilde güncelleştirin AppxManifest.xml :

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

  3. ile MakeAppx.exe yeniden paketleyip yeniden imzalayın.

Tavsiye

Azure Yapıt İmzalama (eski adı Güvenilen İmzalama) kullanılırken bildiriminizdeki yayımcı değeri, sertifika profilinizin Ubject adı alanının altındaki Azure portalında bulunan doğrulanmış kimliğinizle eşleşmelidir.

Uygulama Yükleyicisi ve web teslim hataları

.appinstaller dosyasında şema sürümü uyuşmazlığı

Belirti: Uygulama Yükleyicisi, genellikle geçersiz bir dosya veya desteklenmeyen .appinstaller şema hakkında genel bir hatayla dosyayı ayrıştıramıyor veya işleyemiyor.

Geçerlidir: Windows 10 ve üzeri (sürüme bağımlı — tabloya bakın)

Cause: Uri kök öğesinin <AppInstaller> özniteliği, yüklü Windows sürümünün desteklemediği bir şema sürümünü belirtir.

Windows sürüme göre Schema sürümleri:

Windows sürümü Desteklenen en düşük şema sürümü
Windows 10 sürüm 1709 1.0.0.0
Windows 10 sürüm 1803 1.1.0.0
Windows 10 sürüm 1809 1.2.0.0
Windows 10 sürüm 1903 ve üzeri, Windows 11 1.3.0.0, 1.4.0.0, 1.5.0.0

Düzeltme: Dosyanızdaki .appinstaller şema URI'sini desteklenen en düşük işletim sisteminizin gerektirdiği en düşük sürüme ayarlayın:

<?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">

Eski Windows 10 sürümlerini desteklemeniz gerekiyorsa en son şema sürümünü kullanmaktan kaçının.

Yanlış MIME türüyle veya İçerik Uzunluğu eksik olarak sunulan dosyalar

Belirti: Http/HTTPS uç noktasından yükleme yaparken Uygulama Yükleyicisi başarısız oluyor. Hata genel olabilir, örneğin 0x80072F76 ("Bilinmeyen hata") veya "Uygulama yüklemesi başarısız oldu."

Geçerlidir: Windows 10 ve sonrası

Neden: Web sunucusu, .msix dosyasını yanlış Content-Type üst bilgiyle veya .msixbundle ve .appinstaller dosyalarını yanlış üst bilgiyle sunuyor ya da Content-Length üst bilgisini atlıyor.

Düzeltme: Web sunucunuzu MSIX ile ilgili dosyalara doğru MIME türleriyle hizmet vermek üzere yapılandırın:

Dosya uzantısı Gerekli MIME türü
.msix application/msix
.msixbundle application/msixbundle
.appinstaller application/appinstaller
.appx application/appx
.appxbundle application/appxbundle

Ayrıca her yanıtın geçerli bir Content-Length üst bilgi içerdiğinden emin olun - bu, hem GET hem de HEAD istekleri için geçerlidir.

IIS için MIME tür eşlemelerini web.config ekleyin. Azure Static Web Apps veya GitHub Sayfaları için, bu uzantıların MIME türleri için açık yapılandırma veya özel bir barındırma çözümü gerekebilir.

Eksik bağımlılıklar

Çerçeve paketi yüklenmedi (VCLibs, .NET, Windows Uygulama SDK'sı)

Symptom: Uygulama başarıyla yüklenir ancak başlatma sırasında kilitlenir veya yükleme, Microsoft.VCLibs, Microsoft.WindowsAppRuntime veya Microsoft.NET.Native gibi bir paket ailesi adına başvuruda bulunan bağımlılık hatasıyla başarısız olur.

Applies to: Windows 10 ve üzeri, Windows 11

Ortak çerçeveler ve bunların nereden alınacağı:

Çerçeve Gerekli olduğunda Kaynak
VCLibs (x64/x86/arm64) Uygulama C++ çalışma zamanını kullanır Microsoft Store (otomatik olarak yüklenir) veya direct download
.NET 8 Masaüstü Çalışma Zamanı Uygulama hedefleri .NET 8 Windows Uygulama SDK'sı ile birlikte veya doğrudan indirme
Windows Uygulama SDK'sı (WinAppSDK) Uygulama WinUI 3 veya diğer WinAppSDK API'lerini kullanır Windows Uygulama SDK'sı sürümleri GitHub üzerinde

Geliştirme için düzeltme: Yerel olarak yüklerken Add-AppxPackage, -DependencyPackages parametresini ekleyin veya önce çerçeve paketlerini yükleyin:

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

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

Dağıtım düzeltmesi: Mağaza dışında dağıtılıyorsa, altındaki dosyanıza .appinstaller<Dependencies>çerçeve paketleri ekleyin:

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

Uyarı

Microsoft Store aracılığıyla dağıtılırken çerçeve bağımlılıkları otomatik olarak indirilir ve yüklenir. El ile bağımlılık yönetimi yalnızca dışarıdan yükleme ve kurumsal dağıtımlar için gereklidir.

Ci/CD'de SignTool bulunamadı

Symptom: CI/CD işlem hattı (GitHub Actions, Azure DevOps) 'signtool' is not recognized as an internal or external command veya SignTool.exe: not found gibi bir hatayla başarısız olur.

Applies to: Windows 10 ve üzeri, Windows 11 (kod imzalama makinesi)

Cause: SignTool, Windows SDK'sının bir parçasıdır ve varsayılan olarak standart CI çalıştırıcı görüntülerine dahil değildir.

Fixes:

Option 1 — Windows SDK'sını işlem hattına yükleyin (GitHub Actions):

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

Seçenek 2 — WinApp CLI'yi kullanın (MSIX imzalama için en basit):

- 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 — Azure Yapıt İmzalama kullanın (üretim için önerilir):

- 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

Uyarı

GitHub Eylemi azure/trusted-signing-action (eski hizmet adı) olarak adlandırılır. Bu işlem, Yapıt İmzalama'ya yeniden markalamadan bağımsız olarak resmi bir işlemdir.

CI/CD imzalama kurulumunun tam kılavuzu için bkz. MSIX paketinizi imzalama - uçtan uca kılavuz.

Çalışma zamanı ve sanallaştırma davranışı

MSIX paketleri basit bir uygulama kapsayıcısı içinde çalışır. Hata gibi görünen bazı davranışlar aslında tasarım gereğidir; kapsayıcı, sistemin geri kalanını korumak için dosya ve kayıt defteri işlemlerini durdurur.

Dosya yazma işlemleri neden kayboluyor (VFS dosya yeniden yönlendirmesi)

Belirti: Uygulama çalışma zamanında olduğu gibi C:\Program Files\MyApp\config.ini bir yola dosya yazar, ancak dosya orada görünmez. Uygulama değeri doğru bir şekilde okur, ancak diğer işlemler veya kullanıcılar bunu görmez.

Applies to: Windows 10 ve üzeri, Windows 11

Açıklama: MSIX , Sanal Dosya Sistemi (VFS) yeniden yönlendirmesini kullanır. Korumalı sistem yollarına yazma işlemleri sessizce kullanıcıya özel kapsayıcıya yönlendirilir.

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

Bu tasarım gereğidir; MSIX uygulamalarının paylaşılan sistem konumlarını değiştirmesini engeller ve temiz kaldırmayı destekler.

Seçenekler:

  • Bunun yerine uygulama veri klasörlerini kullanın: Kalıcı olması gereken kullanıcı başına veriler için ApplicationData.Current.LocalFolder veya %LocalAppData%\Packages\<PFN>\LocalState\'ye (WinRT) yazın.
  • Kullanın AppData\Roaming cihazlar arasında dolaşımda olması gereken veriler için.
  • Yeniden yönlendirilen dosyaları görmek için VFS kapsayıcısını inceleyin:%LocalAppData%\Packages\<PackageFamilyName>\LocalCache\

Hangi yolların sanallaştırıldığı hakkında daha fazla bilgi için bkz. MSIX kapsayıcısında çalışma zamanı sorunlarını giderme.

Kayıt defteri yazma işlemleri neden kayboluyor gibi görünüyor (kayıt defteri sanallaştırması)

Belirti: Uygulama çalışma zamanında HKEY_LOCAL_MACHINE\Software\MyApp\'ye yazar, ancak değer diğer işlemler tarafından görülemez ve yeniden yükleme sonrasında kalıcı olmaz.

Applies to: Windows 10 ve üzeri, Windows 11

Açıklama: MSIX, yazma HKLM\Software işlemini durdurur ve bunları sistemin geri kalanından yalıtılmış paket başına kayıt defteri kovanına yönlendirir. Kaldırdığınızda, kovan silinir.

Seçenekler:

  • Kullanıcı başına ayarları olarak HKEY_CURRENT_USER\Software\<AppName> yazın; bunlar sanallaştırılmaz ve kalıcı olmaz.
  • Yapılandırılmış ayarlar depolama için Windows ApplicationData API'lerini kullanın.
  • Mekanizmayı kullanarak kullanıcılar veya işlemler arasında paylaşılması gereken kayıt defteri girdilerini AppxManifest.xml bildirin <Extensions> / <com:Extension> .

MSIX kapsayıcı davranışına daha ayrıntılı bir bakış için bkz. Paketlenmiş masaüstü uygulamalarının Windows üzerinde nasıl çalıştığını anlama.

Windows 10 MSIX sınırlamaları

Bazı MSIX özellikleri için Windows 11 veya belirli bir Windows 10 sürümü gerekir. Windows 10 cihazlara dağıtıyorsanız aşağıdakilere dikkat edin.

Windows 10, sürüm 2004 (derleme 19041) veya üzerini gerektiren özellikler

Özellik En düşük sürüm
Otomatik güncelleştirme 2021 şablonu (ShowPrompt, UpdateBlocksActivation) Windows 10 2004 (19041)
Paket bütünlüğünü sağlama (uap10:PackageIntegrity) Windows 10 2004 (19041)
Uygulama Yükleyicisi otomatik onarımı Windows 10 2004 (19041)
Güvenilir uygulama paketi yüklemeleri için ayrı bir dışarıdan yükleme açma/kapama seçeneği yoktur; Cihazınızı geliştirme için etkinleştirin başlığını, geçerli gereksinimler için inceleyin. Windows 10 2004 (19041)

Windows 11 gerektiren özellikler

Özellik Notlar
Tam paketleme olmadan kısıtlı paket kimliği Windows 11 gerektirir
Dış konuma sahip paketlenmemiş uygulamalar için MSIX desteği (tam platform desteği) Windows 11'de geliştirilmiş bazı API'ler
Makine başına MSIX yükleme performansı iyileştirildi Windows 11 iyileştirmeleri

Windows 10'un 1709 sürümünden daha eski cihazlar

MSIX, 1709 (Fall Creators Update) öncesi Windows 10 sürümlerde yerel olarak desteklenmez. MSIX paketlerini bu cihazlara dağıtmak için MSIX Core kullanın. Bu, alt düzey Windows 10 sürümleri için bir uyumluluk katmanı sağlar.

Manifest uzantıları

Bazı AppxManifest.xml ad alanı uzantıları yalnızca Windows 11. Bunları Windows 10 hedefleyen bir pakette bildirmek, paketleme sırasında şema doğrulamasında başarısız olabilir veya yükleme sırasında reddedilebilir. Her uzantı için listelenen MinOSVersion öğeleri görmek için Uygulama paketi bildirim şeması referansına bakın.

Hata ayıklama ipucu

Belirli bir Windows 10 derlemesinde hangi MSIX özelliklerinin kullanılabilir olduğunu doğrulamak için, işletim sistemi sürümüne göre özellik kullanılabilirliğini listeleyen MSIX özellikleri ve desteklenen platformlar sayfasını denetleyin.

  • Last updated on