Skip to main content
Muitos jogos usam antitrapaça e outros middlewares. Esses componentes normalmente são instalados em cadeia quando o usuário instala o jogo. Um usuário pode instalar um jogo pela Microsoft Store e outro jogo por algum outro canal de distribuição. A plataforma garante que não haja conflitos se os dois jogos instalarem em cadeia o mesmo pacote de middleware. O jogo pode incluir em seu pacote um ou mais arquivos .exe ou .msi arbitrários e solicitar que esses arquivos sejam executados como parte da conclusão da instalação do aplicativo. O recurso de ações de instalação personalizadas destina-se à instalação de software antitrapaça para jogos ou de algum outro middleware redistribuível. Dessa forma, você pode usar exatamente o mesmo arquivo .exe de instalação em cadeia em um MSIX enviado à Microsoft Store e em um arquivo .msi ou .exe enviado por algum outro canal de distribuição. Em aplicativos Win32 tradicionais, o middleware compartilhado normalmente é instalado por meio de arquivos redistribuíveis independentes, que geralmente assumem a forma de um .exe autoextraível ou de um .msi que pode ser incluído com o próprio jogo. Os aplicativos da Microsoft Store modelam dependências como pacotes de estrutura que não são incluídos com o jogo, mas implantados separadamente pela Microsoft Store. Nesse modelo, o manifesto do aplicativo consumidor declara uma dependência de um ou mais pacotes de estrutura. A Microsoft Store então se encarrega de encadear a instalação das dependências. Embora muitos redistribuíveis estejam disponíveis como pacotes de estrutura na Microsoft Store, inevitavelmente haverá alguns redistribuíveis que não estão disponíveis como pacotes de estrutura. Para esses pacotes, a solução é permitir que o jogo inclua o redistribuível no pacote do jogo. Para incluir redistribuíveis .exe ou .msi, você precisa fazer atualizações no seu arquivo MicrosoftGame.config. Essas alterações incluem declarar o tipo de ação personalizada que você deseja usar, bem como sua localização no pacote de instalação. Todos os redistribuíveis devem ser incluídos no pacote e declarados no MicrosoftGame.config. A declaração inclui o caminho para o executável (relativo ao caminho de Folder declarado, que, por sua vez, é relativo ao caminho raiz do próprio pacote). A declaração também inclui todos os argumentos de linha de comando a serem passados ao executável quando ele for executado. Isso é feito por meio da inclusão do elemento CustomInstallActions no arquivo MicrosoftGame.config.

​
CustomInstallActions

O elemento CustomInstallActions contém todas as definições de quais ações de instalação personalizadas devem ser executadas e quando devem ser executadas. Você só pode declarar uma instância desse elemento no seu arquivo MicrosoftGame.config. Ele tem um elemento filho obrigatório, Folder, que é uma cadeia de caracteres que designa a pasta que contém todos os arquivos necessários para todas as ações personalizadas. Essa pasta pode conter subpastas. Você é responsável por garantir que o pacote inclua todas as dependências de quaisquer executáveis de ações personalizadas e que elas estejam no caminho de carregamento apropriado para cada um.
Quando você empacota o título, o makepkg converte esse elemento CustomInstallActions na extensão MSIX windows.customInstall no appxmanifest.xml gerado, em que o elemento equivalente é <CustomInstall>, com Folder expresso como um atributo. Você não cria essa forma <CustomInstall> manualmente - no MicrosoftGame.config, Folder é um elemento filho de CustomInstallActions, conforme mostrado nos exemplos de Alterações no arquivo de configuração do jogo mais adiante neste artigo.
Você não deve colocar nenhum dos executáveis principais do jogo ou outros arquivos na Folder designada. Ela é explicitamente destinada apenas a arquivos de instalação personalizada.
Dentro do elemento CustomInstallActions, o aplicativo pode declarar os elementos filhos InstallActionList, RepairActionList e UninstallActionList. Todos são opcionais: você pode declarar qualquer um deles ou nenhum. Em cada uma dessas listas, você especifica um ou mais itens filhos InstallAction, RepairAction ou UninstallAction. A plataforma executa as ações que você especificar na ordem especificada, com os argumentos de linha de comando especificados.

​
Tipos de ação

Os três nós filhos da extensão de instalação personalizada determinam quando determinadas ações personalizadas são executadas. Há três tipos de ações de instalação personalizadas.
  • Ação de instalação: ações que a plataforma executa antes da primeira inicialização do aplicativo
  • Ação de reparo: ações executadas quando o usuário seleciona Reparar ou Redefinir
  • Ação de desinstalação: ações executadas quando o usuário desinstala o aplicativo
Apesar do nome, uma ação de instalação não é executada quando o pacote é instalado. Cada tipo de ação é executado em um ponto específico do ciclo de vida do aplicativo, e uma InstallAction é executada uma vez, imediatamente antes da primeira inicialização do título (esse é o primeiro ponto em que a plataforma pode apresentar o prompt do UAC necessário). “Install”, “Repair” e “Uninstall” nomeiam a categoria do ciclo de vida à qual a ação pertence - não o momento em que ela é executada. Se você precisar que um trabalho seja realizado no momento real da instalação/download do pacote, as ações de instalação personalizadas não são o mecanismo adequado. Consulte Uso de ações personalizadas para ver a sequência completa.
Normalmente, você especificaria a instalação em cadeia de algum redistribuível como uma InstallAction e, em seguida, especificaria sua desinstalação como uma UninstallAction. No entanto, em alguns casos, você pode optar por instalar sem uma desinstalação correspondente. Nesse cenário, seu aplicativo instala algo que permanece quando ele é desinstalado - e isso pode ser apropriado para redistribuíveis compartilhados por outros aplicativos. Da mesma forma, sua RepairAction pode ser simplesmente uma nova declaração dos executáveis que você especificou para sua InstallAction, e isso é comum. É possível que cada uma das ações que você deseja executar na instalação/reparo/desinstalação exija um executável diferente. O esquema é muito flexível: a plataforma não exige nenhuma das ações. Você tem liberdade para configurar os comportamentos conforme apropriado para cada jogo.
A ação de desinstalação só será executada se uma ação de instalação ou de reparo tiver sido executada. O sistema usa a propriedade Name para rastrear esse estado. Por esse motivo, é importante que as ações de instalação/reparo/desinstalação tenham o mesmo Name.

​
Partes de uma ação

​
File

Para cada ação, você deve especificar o arquivo a ser executado, e esse arquivo deve estar no seu pacote. Se você especificar um caminho, ele será implicitamente relativo ao caminho de Folder de CustomInstallActions. Você não pode especificar um caminho absoluto. Seu caminho não deve começar com uma barra invertida (\).

​
Name

Você deve especificar um Name para a ação. Esse Name deve ser exclusivo dentro do nó Actions pai, mas pode ser compartilhado entre nós Actions diferentes. Por exemplo, você pode especificar File=“MySetup.exe” e Name=“abc123” tanto como InstallAction quanto como RepairAction. Por outro lado, se você tiver dois elementos InstallAction, cada um deles deverá ter um Name diferente. Você deve usar o mesmo Name para o mesmo executável entre versões do pacote, desde que esse executável não mude. O Name é usado como a identidade da ação e permite que a plataforma rastreie quais ações foram executadas com êxito e se elas precisam ser executadas para um pacote atualizado. Se um pacote atualizado especificar uma ação personalizada com um Name que já foi executado com êxito, a plataforma ignorará essa ação na atualização.
Uma diferença na lista de argumentos não constitui uma diferença de identidade. Se você quiser executar o mesmo executável com argumentos diferentes em um pacote atualizado, deverá fornecer um Name diferente. É sua responsabilidade configurar os Names declarados adequadamente e rastreá-los entre versões.

​
Arguments

Cada ação de instalação personalizada tem um terceiro elemento, argument, que permite incluir todos os argumentos necessários para executar o comando do redistribuível.

​
Uso de ações personalizadas

A instalação de software antitrapaça normalmente exige que o usuário tenha privilégios de administrador e, em geral - como as ações personalizadas são um recurso extremamente poderoso -, a plataforma exige privilégios de administrador para qualquer pacote que tenha ações personalizadas. Para operações executadas com privilégios de administrador, o Windows exige que um prompt do Controle de Conta de Usuário (UAC) seja exibido na primeira execução do aplicativo. O fluxo de trabalho do usuário é o seguinte.
  • A página da Microsoft Store do jogo inclui uma descrição dos requisitos, incluindo se a instalação exige privilégios elevados, se a instalação executa uma ação personalizada e o que isso pode significar para o usuário. Essas informações são fornecidas para que o usuário possa tomar uma decisão informada sobre a compra do jogo.
  • Supondo que o usuário esteja de acordo com as restrições e implicações, ele seleciona Instalar.
  • A plataforma detecta que o pacote inclui uma ação personalizada e registra o fato de que a ação personalizada precisa ser executada. No entanto, ela não executa a ação personalizada durante a fase inicial de instalação. Em vez disso, qualquer ação personalizada é executada na primeira vez que o usuário inicia o jogo.
  • Na primeira inicialização do jogo, no momento em que a plataforma está prestes a executar as ações personalizadas, ela exibe um prompt do UAC. O usuário então precisa fornecer credenciais de administrador e aceitar a elevação. Mesmo que um pacote contenha várias ações personalizadas, o usuário recebe apenas um prompt do UAC. Não há outro prompt do UAC para atualizações, a menos que uma ou mais das ações personalizadas tenham sido alteradas. Há um prompt do UAC quando o jogo é desinstalado.
Todas as ações personalizadas devem retornar zero em caso de êxito. Se alguma ação personalizada falhar, a plataforma continuará executando as ações personalizadas restantes e continuará tentando iniciar o aplicativo. A cada inicialização subsequente do aplicativo, a plataforma continua tentando novamente qualquer ação personalizada de instalação com falha ou incompleta até que essa ação seja bem-sucedida. Se o aplicativo não funcionar corretamente diante da falha de uma ação personalizada, o usuário sempre pode acessar a página Configurações do aplicativo e selecionar Reparar ou Redefinir. Reparar/Redefinir não baixa novamente os arquivos do jogo - apenas registra o pacote novamente. Todas as ações personalizadas com falha ou não executadas são registradas novamente para serem executadas. Se você tiver um instalador personalizado que retorna algum valor diferente de zero em caso de êxito, uma opção é encapsular esse instalador em outro executável criado por você, que retorne zero em caso de êxito. A política da Microsoft Store inclui diretrizes sobre quais tipos de middleware/software redistribuível podem ser instalados em cadeia. De modo geral, as instalações em cadeia destinam-se a software compartilhado necessário para executar o jogo. Elas não se destinam à instalação de aplicativos não relacionados ou de outro software.
As ações de instalação personalizadas só têm suporte no pacote MSIXVC principal. Elas não têm suporte em pacotes de estrutura, pacotes opcionais, pacotes de modificação ou qualquer outro tipo de pacote.
As ações personalizadas de instalação, reparo e desinstalação são executadas pelo pipeline de implantação de varejo da Microsoft Store. Elas não são executadas quando você instala o pacote localmente para desenvolvimento - por exemplo, quando você instala um .msixvc solto usando wdApp install ou registra um pacote usando Add-AppxPackage. Uma instalação local de desenvolvimento ainda permite verificar se o seu pacote declara as ações corretamente (elas aparecem no appxmanifest.xml gerado como a extensão windows.customInstall), mas os próprios executáveis das ações personalizadas não são invocados nesse caminho. Para validar a execução das ações de ponta a ponta, instale o título por meio de um fluxo da Store ou de uma sandbox.

​
Executando um MSI como ação de instalação personalizada

No caso de um MSI, você fornece o nome do MSI, e a plataforma executa o msiexec.exe nesse arquivo. Não forneça os argumentos /i, /f ou /x, pois eles são inferidos a partir do tipo da ação (instalação, reparo ou desinstalação) em que ele é declarado. Você não pode fornecer opções para a opção /f. No entanto, você pode fornecer quaisquer outros argumentos opcionais que normalmente seriam fornecidos ao msiexec.exe. Esse é o único cenário em que os argumentos de linha de comando são restritos: para ações que não são MSI, você pode fornecer os argumentos que quiser. Para ações que não são MSI, a plataforma não analisa nem valida os argumentos. A plataforma apenas os repassa ao executável. É sua responsabilidade garantir que os argumentos estejam corretos. Não há suporte direto para MSTs (transformações de MSI). Se você precisar de um MSI/MST, uma possível solução alternativa é criar um .exe independente que encapsule o msiexec para executar seu MSI e aplicar seu MST.

​
Alterações no arquivo de configuração do jogo

Os exemplos XML a seguir demonstram as adições apropriadas a um arquivo MicrosoftGame.config para permitir ações de instalação personalizadas.
No exemplo anterior, todos os executáveis e quaisquer dependências devem ser colocados na pasta MyInstallers que você especificou na raiz do pacote. Dentro dessa pasta, você pode criar qualquer estrutura de subpastas apropriada ao seu aplicativo. Neste exemplo, o caminho para MySetup.exe seria <package root>\MyInstallers\Banana\MySetup.exe. Se esse executável tiver dependências, elas também devem ser colocadas na pasta ou subpasta apropriada. A sequência a seguir mostra como você criaria o manifesto ao longo de várias versões.
Last modified on October 6, 2026