> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Ações de instalação personalizadas

> Ações de instalação personalizadas

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.

<Note>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.</Note>

<Note>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.</Note>

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

<Info>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](#custom-action-usage) para ver a sequência completa.</Info>

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.

<Info>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.</Info>

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

<Info>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.</Info>

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

<Note>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.</Note>

<Note>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.</Note>

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

```xml theme={null}
  <!-- Include CustomInstallActions element. Declare InstallActions, 
  RepairActions and/or UninstallActions as appropriate for your app. --> 
  <DesktopRegistration>
    <!-- ... --> 
    <!-- Other entries omitted for brevity. --> 
    <!-- ... --> 
    <CustomInstallActions>
      <Folder>MyInstallers</Folder>
        <InstallActionList>
          <InstallAction File="CustomInstaller.exe" Name="TaskName" Arguments="/silent /example" />
        </InstallActionList>
        <RepairActionList>
          <RepairAction File="CustomInstaller.exe" Name="TaskName" Arguments="/silent /repair" />
        </RepairActionList>
        <UninstallActionList>
          <UninstallAction File="CustomInstaller.exe" Name="TaskName" Arguments="/silent /remove" />
        </UninstallActionList>
    </CustomInstallActions>
  </DesktopRegistration>
```

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.

```xml theme={null}
<!-- v1 of the game. --> 
    <CustomInstallActions>
      <Folder>MyInstallers</Folder>
      <InstallActionList>
        <InstallAction File="CustomInstaller.exe" Name="TaskName_1" Arguments="/silent /example" />
          <!-- The platform records the successful install of TaskName_1. --> 
      </InstallActionList>
      <RepairActionList>
        <RepairAction File="CustomInstaller.exe" Name="TaskName_1" Arguments="/silent /repair" />
      </RepairActionList>
      <UninstallActionList>
        <UninstallAction File="CustomInstaller.exe" Name="TaskName_1" Arguments="/silent /remove" />
        <!-- The platform records the successful uninstall of TaskName_1. --> 
      </UninstallActionList>
    </CustomInstallActions>
      
<!-- v2 of the game, where the redist is NOT updated. --> 
    <CustomInstallActions>
      <Folder>MyInstallers</Folder>
        <InstallActionList>
          <InstallAction File="CustomInstaller.exe" Name="TaskName_1" Arguments="/silent /example" />
          <!-- The platform detects that we've already installed TaskName_1, so we don't  
          run it again. Therefore, there's no UAC prompt. --> 
        </InstallActionList>
        <RepairActionList>
          <RepairAction File="CustomInstaller.exe" Name="TaskName_1" Arguments="/silent /repair" />
        </RepairActionList>
        <UninstallActionList>
          <UninstallAction File="CustomInstaller.exe" Name="TaskName_1" Arguments="/silent /remove" />
        </UninstallActionList>
      </CustomInstallActions>
 
<!-- v2 of the game, where a redist IS updated. --> 
    <CustomInstallActions>
      <Folder>MyInstallers</Folder>
        <InstallActionList>
          <InstallAction File="CustomInstaller.exe" Name="TaskName_2" Arguments="/silent /example" />
          <!-- The platform detects that we haven't previously run TaskName_2, so we need 
          to run it this time and show a UAC prompt. -->  
        </InstallActionList>
        <RepairActionList>
          <RepairAction File="CustomInstaller.exe" Name="TaskName_1" Arguments="/silent /repair" />
        </RepairActionList>
        <UninstallActionList>
          <UninstallAction File="CustomInstaller.exe" Name="TaskName_1" Arguments="/silent /remove" />
        </UninstallActionList>
      </CustomInstallActions>
```


## Related topics

- [Visão geral de Godot e engines da comunidade](/pt-BR/paths/community-engines/overview.md)
- [Etapas do teste de validação de mídia](/pt-BR/publishing/game-publishing/concepts/certification/certification-media-validation-test-steps.md)
- [Requisitos XBOX testados na certificação para jogos de console XBOX](/pt-BR/publishing/certification/console-cert-tested-requirements.md)
- [Desenvolva um novo título GDK](/pt-BR/home/build-first-title/developing-new-titles.md)
- [Acciones de instalación personalizadas](/es/build/core-features/common/packaging/packaging-custom-install-actions.md)