Guia de resolução de problemas MSIX

Este guia cobre os erros MSIX mais comuns na instalação, assinatura, entrega do App Installer, dependências em falta e comportamento em tempo de execução. Cada secção inclui o sintoma, a causa raiz e a resolução.

Para um registo completo dos eventos de implementação, abra Visualizador de Eventos e navegue para: Registos de Aplicações e Serviços → Microsoft → Windows → AppxDeployment-Server → Operacional

Erros de instalação

0x80070005 — Acesso negado

Sintoma: Add-AppxPackage ou o Instalador de Aplicações falha com código 0x80070005de erro.

Aplica-se: Windows 10 e posteriores, Windows 11

Causas e soluções:

Instalação do pacote bloqueada porque a aplicação está a ser usada

Sintoma: A atualização ou reinstalação falha com um erro a indicar que o pacote está em uso. No Visualizador de Eventos, vê-se que a operação de implementação foi rejeitada.

Aplica-se: Windows 10 e posteriores, Windows 11

Correção: Fecha todas as instâncias em execução da aplicação antes de atualizar. Se a aplicação for um serviço em segundo plano ou tiver uma tarefa em segundo plano registada, pode ser necessário terminar essas tarefas também:

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

Para implementações empresariais, considere agendar atualizações durante as janelas de manutenção usando o Intune ou o Gestor de Configuração.

Incompatibilidade de MinVersion ou arquitetura

Sintoma: A instalação falha com um erro como "O pacote não pôde ser instalado porque não é compatível com esta versão do Windows" ou "O pacote não é aplicável a esta máquina."

Aplica-se a: Windows 10 e posteriores

Causas e soluções:

Add-AppxPackage consegue, mas a aplicação está ausente do Menu Iniciar

Sintoma: O PowerShell reporta sucesso, mas a aplicação não aparece no Menu Iniciar nem na lista de aplicações.

Aplica-se: Windows 10 e posteriores, Windows 11

Causas comuns:

• Instalação por utilizador vs. por máquina: Add-AppxPackage instala apenas para o utilizador atual. Se estiveres a executar como Administrador mas tiveres a aplicação configurada para outro utilizador, usa Add-AppxProvisionedPackage neste caso.
• Pacote registado mas tile não fixado: A aplicação está instalada mas o Menu Iniciar não atualizou. Saia e volte a iniciar sessão, ou verifique as Definições → Apps para confirmar a instalação.
• Entrada em falta no Menu Iniciar no manifesto: Verifique se o elemento <Application> em AppxManifest.xml inclui uma entrada VisualElements com um Square150x150Logo válido.
• Conflito de nomes de família de pacote duplicados: Se uma versão mais recente ou mais antiga do aplicativo já estiver instalada com o mesmo nome de família do pacote, a nova instalação pode substituí-la automaticamente. Verifique com Get-AppxPackage -Name "YourPackageFamilyName".

Erros de assinatura e certificados

Certificado não confiável (0x800B0109)

Sintoma: A instalação falha com erro 0x800B0109 — "Uma cadeia de certificados processada, mas terminada num certificado raiz que não é confiável para o fornecedor de confiança."

Aplica-se: Windows 10 e posteriores, Windows 11

Causa: O certificado usado para assinar o pacote não está nos arquivos de certificados de confiança do dispositivo. Isto é comum ao utilizar certificados auto-assinados para desenvolvimento.

Correção: Importar o certificado de assinatura para a loja Local do Computador → Pessoas Confiáveis do dispositivo (não para a loja do utilizador atual — o App Installer verifica apenas a loja da máquina):

# 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

Para aplicações de produção, utilize um certificado emitido por uma autoridade de certificação de confiança ou Azure Artifact Signing (anteriormente Trusted Signing), que se encadeia à Microsoft Identity Verification Root Certificate Authority — confiável por padrão na versão 1809 do Windows 10 e posteriores, e no Windows 11.

Incompatibilidade no nome do publisher (0x8007000B, ID de evento 150)

Symptoma: O SignTool falha com 0x8007000B, e o Visualizador de Eventos (registo operacional do AppxPackagingOM) mostra ID de evento 150:

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

Aplica-se: Windows 10 e posteriores, Windows 11

Cause: O atributo Publisher em AppxManifest.xml deve corresponder exatamente ao nome do assunto do certificado de assinatura — incluindo todos os campos do nome distinto na mesma ordem.

Correção:

1. Obtenha o nome exato do sujeito do certificado:

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

2. Atualizar AppxManifest.xml para corresponder exatamente:

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

3. Reempacota com MakeAppx.exe e reassina.

Erros no instalador de aplicações e na entrega web

Incompatibilidade de versão do esquema no ficheiro .appinstaller

Sintoma: O App Installer falha em analisar ou processar o .appinstaller ficheiro, frequentemente com um erro genérico sobre ficheiro inválido ou esquema não suportado.

Aplica-se a: Windows 10 e posteriores (dependente da versão — ver tabela)

Cause: O atributo Uri do elemento raiz <AppInstaller> especifica uma versão de esquema que a versão instalada do Windows não suporta.

Versões do esquema por versão do Windows:

Correção: Defina o URI do esquema no seu .appinstaller ficheiro para a versão mínima que o seu sistema operativo menos suportado exige:

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

Evite usar a versão mais recente do esquema se precisar de suportar versões antigas do Windows 10.

Ficheiros servidos com tipo MIME incorreto ou Comprimento de Conteúdo em falta

Sintoma: O instalador de aplicações falha ao instalar a partir de um endpoint HTTP/HTTPS. O erro pode ser genérico, como 0x80072F76 ("Erro desconhecido") ou "Falha na instalação da aplicação."

Aplica-se a: Windows 10 e posteriores

Causa: O servidor web está a servir o .msix, .msixbundle, ou .appinstaller ficheiro com um cabeçalho incorreto Content-Type , ou a omitir o Content-Length cabeçalho.

Correção: Configure o seu servidor web para servir ficheiros relacionados com MSIX com os tipos MIME corretos:

Assegure-se também de que cada resposta inclui um cabeçalho válido Content-Length — isto aplica-se tanto a pedidos GET como HEAD.

Para IIS, adicione mapeamentos do tipo MIME em web.config. Para Aplicações Web Estáticas do Azure ou GitHub Pages, os tipos MIME para estas extensões podem necessitar de configuração explícita ou de uma solução de alojamento personalizada.

Dependências ausentes

Pacote framework não instalado (VCLibs, .NET, SDK de Aplicações Windows)

Sintoma: A aplicação instala-se com sucesso mas crasha no lançamento, ou a instalação falha devido a um erro de dependência que faz referência a um nome de família de pacote como Microsoft.VCLibs, Microsoft.WindowsAppRuntime ou Microsoft.NET.Native.

Aplica-se: Windows 10 e posteriores, Windows 11

Frameworks comuns e onde os obter:

pt-PT: Correção para desenvolvimento: Ao instalar via Add-AppxPackage localmente, adicione o parâmetro -DependencyPackages ou instale primeiro os pacotes de framework:

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

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

Correção para distribuição: Se estiver a distribuir fora da Loja, inclua pacotes framework no seu .appinstaller ficheiro sob <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>

SignTool não encontrado no CI/CD

Symptom: O pipeline CI/CD (GitHub Actions, Azure DevOps) falha com um erro como 'signtool' is not recognized as an internal or external command ou SignTool.exe: not found.

Aplica-se a: Windows 10 e posteriores, Windows 11 (máquina de assinar)

Cause: O SignTool faz parte do SDK Windows e não está incluído por defeito nas imagens padrão do runner CI.

Fixes:

Opção 1 — Instalar Windows SDK no pipeline (GitHub Actions):

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

Opção 2 — Usar a linha de comando do WinApp (mais simples para assinatura 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 }}

Opção 3 — Usar a Assinatura de Artefatos do Azure (recomendado para produção):

- 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

Para uma orientação completa da configuração de assinatura de CI/CD, consulte Assinar o seu pacote MSIX - guia de ponta a ponta.

Tempo de execução e comportamento de virtualização

Os pacotes MSIX correm dentro de um contentor de aplicação leve. Alguns comportamentos que parecem ser bugs são, na verdade, intencionais — o contentor interceta operações de ficheiros e registos para proteger o resto do sistema.

Porque é que a escrita de ficheiros parece estar a desaparecer (redirecionamento de ficheiros VFS)

Sintoma: A aplicação escreve um ficheiro num caminho como C:\Program Files\MyApp\config.ini em tempo de execução, mas o ficheiro não aparece lá. A aplicação lê o valor corretamente, mas outros processos ou utilizadores não o veem.

Aplica-se: Windows 10 e posteriores, Windows 11

Explicação: O MSIX utiliza redirecionamento de Sistema de Ficheiros Virtual (VFS ). As escritas em caminhos protegidos do sistema são silenciosamente redirecionadas para um contentor por utilizador:

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

Isto é intencional — impede que as aplicações MSIX modifiquem as localizações partilhadas do sistema, suportando uma desinstalação limpa.

Opções:

• Use pastas de dados da aplicação em vez disso: Escrever para ApplicationData.Current.LocalFolder (WinRT) ou %LocalAppData%\Packages\<PFN>\LocalState\ para dados de cada utilizador que deverão ser mantidos.
• Utilização AppData\Roaming para dados que devem circular entre dispositivos.
• Inspecione o contentor VFS para ver ficheiros redirecionados: %LocalAppData%\Packages\<PackageFamilyName>\LocalCache\

Para mais detalhes sobre quais caminhos são virtualizados, veja Resolver problemas de tempo de execução num contentor MSIX.

Porque é que as gravações do registo parecem desaparecer (virtualização do registo)

Sintoma: A aplicação escreve em HKEY_LOCAL_MACHINE\Software\MyApp\ durante o tempo de execução, mas o valor não é visível para outros processos ou não sobrevive a uma reinstalação.

Aplica-se: Windows 10 e posteriores, Windows 11

Explicação: O MSIX interceta as gravações em HKLM\Software e redireciona para uma colmeia de registo por pacote que está isolada do resto do sistema. Ao desinstalar, a colmeia é apagada.

Opções:

• Escreva definições por utilizador para HKEY_CURRENT_USER\Software\<AppName> — estas não são virtualizadas e persistem.
• Use as ApplicationData APIs do Windows para o armazenamento de definições estruturadas.
• Declare entradas do registo que devem ser partilhadas entre utilizadores ou processos em AppxManifest.xml usando o mecanismo <Extensions> / <com:Extension>.

Para uma análise mais aprofundada do comportamento dos contentores MSIX, veja Compreenda como as aplicações de ambiente de trabalho empacotadas correm em Windows.

Limitações do Windows 10 MSIX

Algumas funcionalidades do MSIX requerem o Windows 11 ou uma versão específica do Windows 10. Se está a implementar para dispositivos com Windows 10, esteja ciente do seguinte.

Funcionalidades que requerem o Windows 10, versão 2004 (build 19041) ou posterior

Funcionalidades que requerem o Windows 11

Dispositivos Windows 10 mais antigos do que a versão 1709

O MSIX não é suportado nativamente nas versões do Windows 10 anteriores à 1709 (Fall Creators Update). Para implementar pacotes MSIX nesses dispositivos, use MSIX Core, que fornece uma camada de compatibilidade para versões Windows 10 down-level.

Extensões manifestas

Algumas extensões de namespace AppxManifest.xml são exclusivas para o Windows 11. Declará-los num pacote direcionado ao Windows 10 pode falhar na validação de esquema durante o empacotamento ou ser rejeitado durante a instalação. Verifique a referência do esquema do manifesto do pacote de aplicações listada para cada extensão.

Dica de depuração

Para verificar que funcionalidades MSIX estão disponíveis numa build Windows 10 específica, consulte a página de funcionalidades MSIX e plataformas suportadas, que lista a disponibilidade de funcionalidades por versão do sistema operativo.

Recursos relacionados

• Visão geral do pacote Sign an MSIX
• Assine o seu pacote MSIX - guia de ponta a ponta
• Problemas conhecidos e resolução de problemas para o SignTool
• Problemas com o Instalador de Aplicações
• Resolução de problemas de runtime num contentor MSIX
• Resolução de problemas de empacotamento, implementação e consulta de Windows aplicações