Przewodnik rozwiązywania problemów z MSIX

W tym przewodniku opisano najczęstsze błędy MSIX związane z instalacją, podpisywaniem, dostarczaniem Instalatora aplikacji, brakującymi zależnościami i zachowaniem środowiska uruchomieniowego. Każda sekcja zawiera objaw, główną przyczynę i rozwiązanie.

Aby uzyskać pełny dziennik zdarzeń wdrażania, otwórz Podgląd zdarzeń i przejdź do: Applications and Services Logs → Microsoft → Windows → AppxDeployment-Server → Operational

Wskazówka

Aby uzyskać skonsolidowany zestaw diagnostyki, uruchom również zestaw narzędzi aplikacja dla systemu Windows Certification Kit przed dystrybucją pakietu.

Błędy instalacji

0x80070005 — odmowa dostępu

Objaw: Add-AppxPackage lub Instalator aplikacji kończy się niepowodzeniem z kodem 0x80070005błędu .

Dotyczy: Windows 10 oraz nowsze, Windows 11

Przyczyny i poprawki:

Przyczyna Napraw.
Uruchamianie jako użytkownik standardowy bez podniesienia uprawnień, gdy pakiet wymaga instalacji na maszynie Uruchom program PowerShell jako administrator. Aby zainstalować dla wszystkich użytkowników, użyj polecenia Add-AppxProvisionedPackage zamiast Add-AppxPackage.
Oprogramowanie antywirusowe lub oprogramowanie zabezpieczające blokujące plik pakietu Tymczasowo wyłącz skanowanie w czasie rzeczywistym lub dodaj wykluczenie dla .msix / .msixbundle pliku
Pakiet został przygotowany dla innego użytkownika i nie został zainstalowany. Użyj Add-AppxProvisionedPackage aby aprowizować wszystkich użytkowników
Listy kontroli dostępu (ACL) systemu plików blokujące dostęp do odczytu pakietu Sprawdź uprawnienia do pliku icaclspakietu; udziel dostępu do odczytu użytkownikowi instalującemu.

Instalacja pakietu jest zablokowana, ponieważ aplikacja jest używana

Objaw: Aktualizacja lub ponowna instalacja kończy się niepowodzeniem z powodu błędu wskazującego, że pakiet jest używany. W Podgląd zdarzeń widać, że operacja wdrażania została odrzucona.

Dotyczy: Windows 10 oraz nowsze, Windows 11

Poprawka: Zamknij wszystkie działające kopie aplikacji przed aktualizacją. Jeśli aplikacja jest usługą w tle lub ma zarejestrowane zadanie w tle, może być konieczne zakończenie tych zadań, jak również:

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

W przypadku wdrożeń w przedsiębiorstwie, należy rozważyć planowanie aktualizacji podczas okna serwisowego przy użyciu Intune lub Configuration Manager.

Minimalna wersja lub niezgodność architektury

Symptom: Instalacja kończy się niepowodzeniem z powodu błędu takiego jak "Nie można zainstalować pakietu, ponieważ nie jest zgodny z tą wersją Windows" lub "Pakiet nie ma zastosowania do tej maszyny".

Dotyczy systemu: Windows 10 i nowszych wersji

Przyczyny i poprawki:

Przyczyna Napraw.
Pakiet MinVersion w manifeście jest wyższy niż wersja systemu operacyjnego Tworzenie oddzielnego pakietu przeznaczonego dla zainstalowanej wersji systemu operacyjnego lub aktualizowanie urządzenia
Niezgodność architektury (np. pakiet arm64 na urządzeniu x64) Kompilowanie i dystrybuowanie poprawnego wariantu architektury; używanie pakietu (.msixbundle) do obsługi wielu architektur z jednego pliku
Pakiet jest przeznaczony dla interfejsu API wyłącznie dla Windows 11 bez weryfikacji zgodności Dodaj wpis TargetDeviceFamily dla systemów Windows 10 i Windows 11 lub zabezpiecz wywołanie API przez sprawdzanie wersji w czasie wykonywania.

Uwaga / Notatka

Używaj .msixbundle plików podczas dystrybucji do środowisk architektury mieszanej. Pakiet zawiera pakiety dla wielu architektur i Windows wybiera poprawne podczas instalacji.

Add-AppxPackage kończy się powodzeniem, ale w menu Start brakuje aplikacji

Objaw: program PowerShell zgłasza powodzenie, ale aplikacja nie jest wyświetlana na liście Menu Start lub aplikacji.

Dotyczy: Windows 10 oraz nowsze, Windows 11

Typowe przyczyny:

  • Instalacja na użytkownika vs. na maszynę: Add-AppxPackage jest instalowana tylko dla bieżącego użytkownika. Jeśli używasz konta administratora, ale oczekujesz aplikacji dla innego użytkownika, użyj Add-AppxProvisionedPackage zamiast tego.
  • Pakiet zarejestrowany, ale kafelek nie przypięty w menu Start: aplikacja jest zainstalowana, ale menu Start nie zostało odświeżone. Wyloguj się i zaloguj się ponownie lub sprawdź ustawienia → Apps , aby potwierdzić instalację.
  • Brak wpisu menu Start w manifeście: zweryfikuj, czy element <Application> w AppxManifest.xml zawiera wpis VisualElements z prawidłowym Square150x150Logo.
  • Konflikt zduplikowanej nazwy rodziny pakietów: jeśli nowsza lub starsza wersja aplikacji jest już zainstalowana z tą samą nazwą rodziny pakietów, nowa instalacja może w trybie dyskretnym zastąpić ją. Skonsultuj się z Get-AppxPackage -Name "YourPackageFamilyName".

Błędy podpisywania i certyfikatu

Uwaga / Notatka

Aby uzyskać szczegółowe kody błędów i flag narzędzia SignTool, zobacz Znane problemy i rozwiązywanie problemów dotyczących narzędzia SignTool.

Certyfikat nie jest zaufany (0x800B0109)

Objaw: Instalacja kończy się niepowodzeniem z powodu błędu 0x800B0109 — "Łańcuch certyfikatów został przetworzony, ale zakończył się na certyfikacie głównym, który nie jest zaufany przez urząd certyfikacji."

Dotyczy: Windows 10 i nowsze, Windows 11

Przyczyna: Certyfikat używany do podpisywania pakietu nie znajduje się w zaufanych magazynach certyfikatów urządzenia. Jest to typowe w przypadku używania certyfikatów z podpisem własnym na potrzeby programowania.

Poprawka: Zaimportuj certyfikat podpisywania do lokalnego magazynu komputera → Zaufane osoby (a nie bieżącego magazynu użytkownika — Instalator aplikacji sprawdza tylko magazyn lokalny komputera):

# 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

Ważna

Nie należy importować certyfikatów podpisywania do magazynu zaufanych głównych urzędów certyfikujących, chyba że certyfikat jest certyfikatem nadrzędnego urzędu certyfikacji. Importowanie niezaufanych certyfikatów z podpisem własnym osłabia stan zabezpieczeń urządzenia.

W przypadku aplikacji produkcyjnych należy użyć certyfikatu wystawionego przez zaufany urząd certyfikacji lub Azure Artifact Signing (wcześniej Trusted Signing), który łączy się z Głównym Urzędem Certyfikacji Weryfikacji Tożsamości Microsoft — domyślnie zaufanym na Windows 10 w wersji 1809 lub nowszej oraz w Windows 11.

Niezgodność nazwy wydawcy (0x8007000B, identyfikator zdarzenia 150)

Symptom: Narzędzie SignTool kończy się niepowodzeniem z 0x8007000B, a Podgląd Zdarzeń (dziennik operacyjny AppxPackagingOM) pokazuje 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).

Dotyczy: Windows 10 i nowsze, Windows 11

Przyczyna: Atrybut Publisher w AppxManifest.xml musi dokładnie odpowiadać nazwie nazwa podmiotu certyfikatu podpisującego — w tym wszystkich pól nazw wyróżniających w tej samej kolejności.

Poprawka:

  1. Pobierz dokładną nazwę podmiotu z certyfikatu:

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

  2. Aktualizuj AppxManifest.xml , aby dokładnie dopasować:

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

  3. Ponownie zapakuj przy użyciu MakeAppx.exe i podpisz ponownie.

Wskazówka

pl-PL: W przypadku korzystania z podpisywania artefaktów Azure (wcześniej zaufanego podpisywania) wartość nazwy wydawcy w manifeście musi być zgodna z Twoją zweryfikowaną tożsamością — znajdującą się w portalu Azure w obszarze Nazwa podmiotu.

Błędy instalatora aplikacji i dostarczania przez Internet

Niezgodność wersji schematu w pliku .appinstaller

Objaw: Instalator aplikacji nie może przeanalizować lub przetworzyć .appinstaller pliku, często z ogólnym błędem dotyczącym nieprawidłowego pliku lub nieobsługiwanego schematu.

Dotyczy: Windows 10 i późniejsze wersje (zależne od wersji — zobacz tabelę)

Cause: atrybut Uri elementu głównego <AppInstaller> określa wersję schematu, która zainstalowana wersja Windows nie obsługuje.

Wersje schematu według wydania Windows:

wersja Windows Minimalna obsługiwana wersja schematu
Windows 10 w wersji 1709 1.0.0.0
Windows 10 w wersji 1803 1.1.0.0
Windows 10 w wersji 1809 1.2.0.0
Windows 10 w wersji 1903 lub nowszej Windows 11 1.3.0.0, 1.4.0.0, 1.5.0.0

Napraw: Ustaw identyfikator URI schematu w pliku .appinstaller na minimalną wersję wymaganą przez najniższy obsługiwany system operacyjny:

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

Unikaj używania najnowszej wersji schematu, jeśli potrzebujesz obsługi starszych wersji Windows 10.

Pliki obsługiwane z nieprawidłowym typem MIME lub brakującym nagłówkiem Content-Length

Objaw: Instalator aplikacji nie działa przy instalacji z punktu końcowego HTTP/HTTPS. Błąd może być ogólny, taki jak 0x80072F76 ("Nieznany błąd") lub "Instalacja aplikacji nie powiodła się".

Dotyczy systemu: Windows 10 i nowszych wersji

Przyczyna: serwer internetowy obsługuje .msixplik , .msixbundlelub .appinstaller z niepoprawnym Content-Type nagłówkiem lub pomija Content-Length nagłówek.

Poprawka: Skonfiguruj serwer internetowy tak, aby obsługiwał pliki związane z plikiem MSIX z poprawnymi typami MIME:

Rozszerzenie pliku Wymagany typ MIME
.msix application/msix
.msixbundle application/msixbundle
.appinstaller application/appinstaller
.appx application/appx
.appxbundle application/appxbundle

Upewnij się również, że każda odpowiedź zawiera prawidłowy nagłówek Content-Length — dotyczy to zarówno żądań GET, jak i HEAD.

W przypadku usług IIS dodaj mapowania typów MIME w pliku web.config. W przypadku Azure Static Web Apps lub GitHub Pages typy MIME dla tych rozszerzeń mogą wymagać jawnej konfiguracji lub niestandardowego rozwiązania hostingu.

Brak zależności

Pakiet framework nie został zainstalowany (VCLibs, .NET, Zestaw SDK do aplikacji systemu Windows)

Symptom: Aplikacja jest instalowana pomyślnie, ale ulega awarii podczas uruchamiania lub instalacja kończy się niepowodzeniem z powodu błędu zależności odwołującego się do nazwy rodziny pakietów, takiej jak Microsoft.VCLibs, Microsoft.WindowsAppRuntime lub Microsoft.NET.Native.

Dotyczy: Windows 10 oraz nowsze, Windows 11

Typowe struktury i miejsca ich pobierania:

Framework Wymagane, gdy Źródło
VCLibs (x64/x86/arm64) Aplikacja używa środowiska uruchomieniowego języka C++ Microsoft Store (instalowane automatycznie) lub direct download
.NET 8 Środowisko uruchomieniowe pulpitu Aplikacja jest przeznaczona na .NET 8 Dołączone do Zestaw SDK do aplikacji systemu Windows; lub direct download
Zestaw SDK do aplikacji systemu Windows (WinAppSDK) Aplikacja używa interfejsów API WinUI 3 lub innych interfejsów API WinAppSDK Wydania Zestaw SDK do aplikacji systemu Windows na GitHub

Poprawka dotycząca programowania: podczas instalowania za pośrednictwem Add-AppxPackage środowiska lokalnego dodaj -DependencyPackages parametr lub najpierw zainstaluj pakiety struktury:

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

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

Poprawka dotycząca dystrybucji: w przypadku dystrybucji poza Sklepem uwzględnij pakiety frameworku w swoim pliku w sekcji .appinstaller<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>

Uwaga / Notatka

Podczas dystrybucji za pośrednictwem Microsoft Store zależności struktury są automatycznie pobierane i instalowane. Ręczne zarządzanie zależnościami jest wymagane tylko do ładowania zewnętrznego i wdrożeń w przedsiębiorstwie.

Brak narzędzia SignTool w CI/CD

Symptom: potok zadań ciągłej integracji/ciągłego wdrażania (GitHub Actions, Azure DevOps) kończy się niepowodzeniem z błędem takim jak 'signtool' is not recognized as an internal or external command lub SignTool.exe: not found.

Dotyczy: Windows 10 i nowsze, Windows 11 (urządzenie podpisujące)

Przyczyna: SignTool jest częścią zestawu SDK Windows i nie jest domyślnie uwzględniany w standardowych obrazach uruchamiania CI.

Fixes:

Option 1 — zainstaluj zestaw SDK Windows w pipeline (GitHub Actions):

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

Opcja 2 — użyj interfejsu wiersza polecenia usługi WinApp (najprostszego do podpisywania 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 }}

Opcja 3 — Podpisywanie artefaktów Azure (zalecane dla produkcji):

- 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

Uwaga / Notatka

Akcja GitHub nosi nazwę azure/trusted-signing-action (była nazwa usługi). Jest to oficjalna akcja niezależnie od zmieniania nazwy na Artifact Signing.

Aby zapoznać się z pełnym przewodnikiem dotyczącym konfiguracji podpisywania CI/CD, zobacz Kompletny przewodnik po podpisywaniu pakietu MSIX.

Zachowanie środowiska uruchomieniowego i wirtualizacji

Pakiety MSIX działają wewnątrz uproszczonego kontenera aplikacji. Niektóre zachowania, które wydają się być błędami, są faktycznie zamierzone — kontener przechwytuje operacje plików i rejestru w celu ochrony reszty systemu.

Dlaczego zapisy plików wydają się znikać (przekierowanie plików VFS)

Objaw: aplikacja zapisuje plik w ścieżce podobnej C:\Program Files\MyApp\config.ini do środowiska uruchomieniowego, ale plik nie jest tam widoczny. Aplikacja odczytuje wartość z powrotem poprawnie, ale inne procesy lub użytkownicy tego nie widzą.

Dotyczy: Windows 10 i nowsze wersje, w tym Windows 11

Wyjaśnienie: MSIX używa przekierowania wirtualnego systemu plików (VFS). Zapisy do chronionych ścieżek systemowych są w trybie dyskretnym przekierowywane do kontenera dla poszczególnych użytkowników:

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

To jest zamierzone — uniemożliwia aplikacjom MSIX modyfikowanie udostępnionych lokalizacji systemowych i wspiera czystą dezinstalację.

Opcje:

  • Zamiast tego używaj folderów danych aplikacji: zapisuj do ApplicationData.Current.LocalFolder (WinRT) lub %LocalAppData%\Packages\<PFN>\LocalState\ dla danych poszczególnych użytkowników, które powinny być utrwalane.
  • Używać AppData\Roaming w przypadku danych, które powinny być przenoszone między urządzeniami.
  • Sprawdź kontener VFS, aby wyświetlić przekierowane pliki: %LocalAppData%\Packages\<PackageFamilyName>\LocalCache\

Aby uzyskać więcej informacji na temat ścieżek zwirtualizowanych, zobacz Rozwiązywanie problemów ze środowiskiem uruchomieniowym w kontenerze MSIX.

Dlaczego zapisy rejestru wydają się zniknąć (wirtualizacja rejestru)

Objaw: aplikacja zapisuje dane w HKEY_LOCAL_MACHINE\Software\MyApp\ czasie wykonywania, ale wartość nie jest widoczna dla innych procesów ani nie przetrwa ponownej instalacji.

Dotyczy: Windows 10 i nowsze wersje, Windows 11

Wyjaśnienie: MSIX przechwytuje zapisy i przekierowuje je do obszaru rejestru poszczególnych pakietów, który jest odizolowany od reszty systemu. Po odinstalowaniu gałąź zostanie usunięta.

Opcje:

  • Zapisz ustawienia dla użytkownika do HKEY_CURRENT_USER\Software\<AppName> — nie są one zwirtualizowane i zostają zachowane.
  • Użyj interfejsów API Windows ApplicationData do przechowywania ustawień w sposób uporządkowany.
  • Zadeklaruj wpisy rejestru, które muszą być współużytkowane przez użytkowników lub procesy za pomocą mechanizmu <Extensions> / <com:Extension> w AppxManifest.xml.

Aby dowiedzieć się więcej na temat zachowania kontenera MSIX, zobacz Zrozum, jak pakowane aplikacje na komputery stacjonarne działają na Windows.

Windows 10 ograniczenia MSIX

Niektóre funkcje MSIX wymagają Windows 11 lub określonej wersji Windows 10. Jeśli wdrażasz na urządzeniach Windows 10, pamiętaj o następujących kwestiach.

Funkcje wymagające Windows 10, wersja 2004 (kompilacja 19041) lub nowsza

Funkcja Minimalna wersja
Schemat automatycznej aktualizacji 2021 (ShowPrompt, UpdateBlocksActivation) Windows 10 2004 (19041)
Wymuszanie integralności pakietów (uap10:PackageIntegrity) Windows 10 2004 (19041)
Automatyczna naprawa Instalatora aplikacji Windows 10 2004 (19041)
Nie ma oddzielnego przełącznika zasad ładowania aplikacji metodą sideloadingu dla instalacji pakietu zaufanej aplikacji; zobacz Włącz urządzenie deweloperskie dla bieżących wymagań. Windows 10 2004 (19041)

Funkcje wymagające Windows 11

Funkcja Notatki
Tożsamość pakietu o rozrzedzonej strukturze bez pełnego opakowania Wymaga Windows 11
Obsługa msiX dla niezapakowanych aplikacji z lokalizacją zewnętrzną (pełna obsługa platformy) Niektóre interfejsy API ulepszone w Windows 11
Zwiększona wydajność instalacji MSIX na każdą maszynę optymalizacje Windows 11

Urządzenia z systemem Windows 10 starsze niż wersja 1709

MSIX nie jest natywnie obsługiwany w wersjach Windows 10 przed 1709 (Fall Creators Update). Aby wdrożyć pakiety MSIX na tych urządzeniach, użyj MSIX Core która zapewnia warstwę zgodności dla wersji Windows 10 na poziomie podrzędnym.

Rozszerzenia manifestu

Niektóre rozszerzenia przestrzeni nazw AppxManifest.xml są dostępne tylko w Windows 11. Deklarowanie ich w pakiecie przeznaczonym dla Windows 10 może zakończyć się niepowodzeniem weryfikacji schematu podczas pakowania lub odrzucone podczas instalacji. Sprawdź dokumentację schematu manifestu pakietu aplikacji dla MinOSVersion każdego rozszerzenia.

Porada dotycząca debugowania

Aby sprawdzić, jakie funkcje MSIX są dostępne w określonej kompilacji Windows 10, sprawdź funkcje MSIX i obsługiwane platformy która zawiera listę dostępności funkcji według wersji systemu operacyjnego.

  • Last updated on