Guia de solução de problemas do MSIX

Este guia aborda os erros MSIX mais comuns na instalação, assinatura, entrega do Instalador de Aplicativo, dependências ausentes e comportamento de runtime. Cada seção inclui o sintoma, a causa raiz e a resolução.

Para obter um log completo de eventos de implantação, abra o Visualizador de Eventos e navegue até: Aplicativos e Serviços → Microsoft → Windows → AppxDeployment-Server → Operacional

Erros de instalação

0x80070005 – Acesso negado

Sintoma: Add-AppxPackage ou o Instalador de Aplicativo falha com o código 0x80070005de erro.

Aplicável a: Windows 10 e posterior, Windows 11

Causas e correções:

Instalação do pacote bloqueada porque o aplicativo está em uso

Sintoma: a atualização ou reinstalação falha com um erro indicando que o pacote está em uso. Em Visualizador de Eventos, você verá que a operação de implantação foi rejeitada.

Aplica-se a: Windows 10 e posterior, Windows 11

Correção: feche todas as instâncias em execução do aplicativo antes de atualizar. Se o aplicativo for um serviço em segundo plano ou tiver uma tarefa em segundo plano registrada, talvez seja necessário encerrá-los também:

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

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

Incompatibilidade da minVersion ou da arquitetura

Symptom: 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 este computador".

Aplicável a: Windows 10 e posterior

Causas e correções:

Add-AppxPackage é bem-sucedido, mas o aplicativo está ausente no Menu Iniciar

Sintoma: o PowerShell relata êxito, mas o aplicativo não aparece no Menu Iniciar ou na lista de aplicativos.

Aplica-se a: Windows 10 e posterior, Windows 11

Causas comuns:

• Instalação por usuário versus por computador: Add-AppxPackage instala somente para o usuário atual. Se você estiver executando como Administrador, mas pretende que o aplicativo seja para outro usuário, use Add-AppxProvisionedPackage em vez disso.
• Pacote registrado, mas bloco não fixado: o aplicativo está instalado, mas o Menu Iniciar não foi atualizado. Saia e entre novamente ou verifique as Configurações → Aplicativos para confirmar a instalação.
• Entrada ausente no menu Iniciar no manifesto: verifique se o <Application> inclui um elemento AppxManifest.xml com uma entrada VisualElements com um Square150x150Logo válido.
• Conflito de nome de família de pacote duplicado: se uma versão mais recente ou mais antiga do aplicativo já estiver instalada com o mesmo nome de família de pacotes, a nova instalação poderá substituí-la silenciosamente. Verifique com Get-AppxPackage -Name "YourPackageFamilyName".

Erros de assinatura e certificado

Certificado não confiável (0x800B0109)

Sintoma: a instalação falha com o erro 0x800B0109 : "Uma cadeia de certificados processada, mas encerrada em um certificado raiz que não é confiável pelo provedor de confiança".

Aplica-se a: Windows 10 e posterior, Windows 11

Causa: o certificado usado para assinar o pacote não está nos repositórios de certificados confiáveis do dispositivo. Isso é comum ao usar certificados autoassinados para desenvolvimento.

Correção: importar o certificado de autenticação para o computador local do dispositivo → repositório de pessoas confiáveis (não o repositório de usuários atual — o Instalador de Aplicativos verifica apenas o repositório de máquinas):

# 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 aplicativos de produção, use um certificado emitido por uma AC confiável ou Azure Artifact Signing (antigo Trusted Signing), que é encadeado com a autoridade de certificação raiz de verificação de identidade da Microsoft, confiável por padrão no Windows 10 versão 1809 e posterior e no Windows 11.

incompatibilidade de nome do publicador (0x8007000B, ID do evento 150)

Symptom: o SignTool falha com 0x8007000B e o Visualizador de Eventos (log operacional do AppxPackagingOM) mostra ID do 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 a: Windows 10 e versões posteriores, Windows 11

Cause: o atributo Publisher em AppxManifest.xml deve corresponder exatamente ao nome subject do certificado de assinatura , incluindo todos os campos de nome diferenciados 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. Atualize AppxManifest.xml para corresponder exatamente:

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

3. Reempacote com MakeAppx.exe e assine novamente.

Erros de instalação de aplicativo e entrega na Web

Incompatibilidade de versão do esquema no arquivo .appinstaller

Sintoma: o Instalador de Aplicativo falha ao analisar ou processar o .appinstaller arquivo, geralmente com um erro genérico sobre um arquivo inválido ou um esquema sem suporte.

Aplicativos para: Windows 10 e posteriores (dependentes da versão – consulte a tabela)

Cause: o atributo Uri do elemento raiz <AppInstaller> especifica uma versão de esquema à qual a versão instalada do Windows não dá suporte.

Versões de schema por lançamento do Windows

Correção: defina o URI do esquema em seu .appinstaller arquivo para a versão mínima que seu sistema operacional com menor suporte requer:

<?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 de esquema mais recente se precisar dar suporte a versões de Windows 10 mais antigas.

Arquivos servidos com tipo MIME incorreto ou comprimento de conteúdo ausente

Sintoma: o Instalador de Apps 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 do aplicativo".

Aplica-se a: Windows 10 ou posterior

Causa: o servidor Web está servindo o .msixarquivo, .msixbundleou .appinstaller com um cabeçalho incorreto Content-Type ou omitindo o Content-Length cabeçalho.

Correção: configure o servidor Web para atender arquivos relacionados ao MSIX com os tipos MIME corretos:

Verifique também se cada resposta inclui um cabeçalho válido Content-Length — isso se aplica tanto a solicitações GET quanto a HEAD.

Para o IIS, adicione mapeamentos de tipo MIME em web.config. Para páginas Aplicativos Web Estáticos do Azure ou GitHub, os tipos MIME para essas extensões podem precisar de uma configuração explícita ou de uma solução de hospedagem personalizada.

Dependências ausentes

Pacote de estrutura não instalado (VCLibs, .NET, SDK do Aplicativo Windows)

Symptom: o aplicativo é instalado com êxito, mas falha na inicialização ou a instalação falha com um erro de dependência que faz referência a um nome de família de pacotes como Microsoft.VCLibs, Microsoft.WindowsAppRuntime ou Microsoft.NET.Native.

Aplica-se a: Windows 10 e posterior, Windows 11

Estruturas comuns e onde obtê-las:

Correção para desenvolvimento: ao instalar via Add-AppxPackage localmente, adicionar o parâmetro -DependencyPackages ou instale os pacotes da estrutura primeiro.

# 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 distribuindo fora da Loja, inclua pacotes de estrutura no arquivo .appinstallerem<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 em CI/CD

Symptom: o pipeline de 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.

Applies to: Windows 10 e posterior, Windows 11 (máquina de assinatura)

Cause: o SignTool faz parte do SDK do Windows e não está incluído em imagens padrão do executor de CI por padrão.

Fixes:

Option 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 CLI do WinApp (mais simples para assinatura do 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 — Utilizar 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 obter um passo a passo completo da configuração de assinatura de CI/CD, consulte Assinar seu pacote MSIX – guia de ponta a ponta.

Comportamento de runtime e virtualização

Os pacotes MSIX são executados dentro de um contêiner de aplicativo leve. Alguns comportamentos que parecem ser bugs são, na verdade, por design– o contêiner intercepta operações de arquivo e registro para proteger o restante do sistema.

Por que as gravações de arquivo parecem desaparecer (redirecionamento de arquivo VFS)

Sintoma: o aplicativo grava um arquivo em um caminho como C:\Program Files\MyApp\config.ini em runtime, mas o arquivo não aparece lá. O aplicativo lê o valor de volta corretamente, mas outros processos ou usuários não o veem.

Aplica-se a: Windows 10 e posterior, Windows 11

Explicação: o MSIX usa o redirecionamento do VFS (Virtual File System ). As gravações nos caminhos protegidos do sistema são redirecionadas de forma silenciosa para um contêiner por usuário.

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

Isso é por design – ele impede que aplicativos MSIX modifiquem os locais do sistema compartilhado, dando suporte à desinstalação limpa.

Opções:

• Em vez disso, use pastas de dados do aplicativo: Gravar em ApplicationData.Current.LocalFolder (WinRT) ou %LocalAppData%\Packages\<PFN>\LocalState\ para dados do usuário que devem persistir.
• Usar AppData\Roaming para dados que devem percorrer dispositivos.
• Inspecione o contêiner do VFS para ver os arquivos redirecionados: %LocalAppData%\Packages\<PackageFamilyName>\LocalCache\

Para obter mais detalhes sobre quais caminhos são virtualizados, consulte Solucionar problemas de runtime em um contêiner MSIX.

Por que as gravações do Registro parecem desaparecer (virtualização do Registro)

Sintoma: o aplicativo grava HKEY_LOCAL_MACHINE\Software\MyApp\ em tempo de execução, mas o valor não é visível para outros processos nem sobrevive a uma reinstalação.

Aplica-se a: Windows 10 e posterior, Windows 11

Explicação: O MSIX intercepta gravações HKLM\Software e as redireciona para um hive de registro por pacote isolado do restante do sistema. Ao desinstalar, o hive é excluído.

Opções:

• Escreva as configurações por usuário para HKEY_CURRENT_USER\Software\<AppName> : elas não são virtualizadas e persistem.
• Use as APIs do Windows ApplicationData para o armazenamento de configurações estruturadas.
• Declare entradas do Registro que devem ser compartilhadas entre usuários ou processos no AppxManifest.xml usando o <Extensions> / <com:Extension> mecanismo.

Para obter uma visão mais detalhada do comportamento do contêiner MSIX, veja Entenda como os aplicativos de área de trabalho empacotados são executados no Windows.

limitações do MSIX Windows 10

Alguns recursos msix exigem Windows 11 ou uma versão de Windows 10 específica. Se você estiver implantando em dispositivos Windows 10, esteja ciente do seguinte.

Recursos que exigem Windows 10, versão 2004 (build 19041) ou posterior

Recursos que exigem Windows 11

Windows 10 dispositivos anteriores à versão 1709

O MSIX não tem suporte nativo em Windows 10 versões anteriores à 1709 (Fall Creators Update). Para implantar pacotes MSIX nesses dispositivos, use MSIX Core, que fornece uma camada de compatibilidade para versões de Windows 10 de nível inferior.

Extensões de manifesto

Algumas extensões de namespace AppxManifest.xml são somente Windows 11. Declarar esses elementos em um pacote direcionado para o Windows 10 pode falhar na validação do esquema durante a embalagem ou ser rejeitado durante a instalação. Verifique a referência de esquema de manifesto do pacote do aplicativo para cada extensão listada.

Dica de depuração

Para verificar quais recursos MSIX estão disponíveis em um build específico do Windows 10, consulte a página MSIX e plataformas compatíveis, que lista a disponibilidade de recursos por versão do sistema operacional.

Recursos relacionados

• Assinar um pacote MSIX: visão geral
• Assinar seu pacote MSIX – guia de ponta a ponta
• Problemas conhecidos e solução de problemas para SignTool
• Solucionar problemas do Instalador de Aplicativos
• Solucionar problemas de runtime em um contêiner MSIX
• Solução de problemas no empacotamento, implantação e consulta de aplicativos Windows