Pré-instalar aplicativos usando DISM

Artigo
05/09/2023

Observação

Interessado em pré-instalar aplicativos da Microsoft Store, mas você não é um OEM? Para obter informações sobre o sideload de aplicativos para organizações, consulte Sideload Apps with DISM( Sideload Apps with DISM).

Este tópico aborda como pré-instalar aplicativos para que eles sejam incluídos como parte de uma imagem do Windows.

Dica

Os HSAs (Aplicativos de Suporte de Hardware) são aplicativos da Microsoft Store e as instruções a seguir se aplicam.

Trabalhar com pacotes de aplicativos

Use o DISM para provisionar um aplicativo offline em uma imagem. Você pode usar o DISM no Prompt de Comando ou os cmdlets DISM no Windows PowerShell.

Nas versões anteriores do Windows 10, aplicativos Universais pré-instalados e aplicativos da Microsoft Store tinham que ser fixados no menu Iniciar. O Windows removeria aplicativos que foram pré-instalados, mas não fixados no menu Iniciar.

A partir do Windows 10, versão 1803, os aplicativos podem ser pré-instalados sem serem fixados no Menu Iniciar quando você usa DISM /add-provisionedappxpackage com a opção /region . Ao pré-instalar um aplicativo, você pode optar por deixar o aplicativo fora do LayoutModification.xml e o aplicativo será instalado com êxito sem aparecer como um bloco Menu Iniciar. Quando uma lista de regiões NÃO for especificada, o aplicativo será provisionado somente se ele estiver fixado para iniciar o layout.

Extrair os arquivos do pacote

Navegue até a pasta em que você salvou os pacotes de aplicativos baixados do Painel de Parceiros.
Clique com o botão direito do mouse em cada pasta .zip que contém os arquivos do pacote do aplicativo. Clique em Extrair Tudo e selecione um local para salvar as pastas de arquivo de pacote.

A pasta contém todos os arquivos não empacotados para o pacote, incluindo um pacote main, quaisquer pacotes de dependência e o arquivo de licença.

Importante

Não modifique a pasta depois de extrair os arquivos do pacote. Se você alterar, adicionar ou remover arquivos na pasta, o aplicativo falhará durante a instalação ou inicialização. Mesmo navegar na pasta pode causar problemas.

Você precisará usar o arquivo de licença dos arquivos de pacote para testar sua imagem provisionada. Criar seu próprio arquivo de dados personalizado não permitirá que você teste com precisão um aplicativo pré-instalado por um OEM.

Para o provisionamento offline de um aplicativo em uma imagem, você pode usar a ferramenta Dism.exe ou os cmdlets DISM em Windows PowerShell para adicionar um aplicativo de uma pasta de arquivos descompactados.

Pré-instalar um aplicativo assinado pela Microsoft Store com DISM

Abra o Prompt de Comando como administrador.

Monte uma imagem do Windows para a qual você deseja atender:

Dism /Mount-Image /ImageFile:c:\images\myimage.wim /Index:1 /mountdir:c:\test\offline

Adicione o aplicativo à imagem montada. Use as /PackagePath opções e /DependencyPackagePath .
- Packagepath é o caminho para o pacote .appx ou o arquivo de pacote
- DependencyPackagePath é o caminho para especificar cada pacote de dependência. Você pode ter mais de uma dependência por comando.
- Novo no Windows 10, versão 1803: use a opção Region ao adicionar aplicativos. Region permite adicionar um aplicativo sem precisar fixar o aplicativo no Menu Iniciar.
```
Dism /Image:c:\test\offline /Add-ProvisionedAppxPackage /PackagePath:c:\downloads\package.appxbundle /DependencyPackagePath:c:\downloads\dependency1.appx /DependencyPackagePath:c:\downloads\dependency2.appx /LicensePath=c:\downloads\package_License1.xml /region=all"
```
Consulte Opções de linha de comando de manutenção do pacote de aplicativos DISM para obter informações sobre como trabalhar com pacotes de aplicativos, incluindo a nova opção /region..
Fixe o aplicativo no Menu Iniciar.
- Se você não especificou /region ao pré-instalar o aplicativo, fixe o aplicativo no Menu Iniciar com LayoutModification.xml.
  
  or
- Se você especificou /region ao pré-instalar o aplicativo e deseja fixar o aplicativo no Menu Iniciar para regiões específicas, use o RequiredStartGroups Region="region1|region2" elemento em LayoutModification.xml para especificar as regiões em que deseja que o aplicativo apareça.
Salve as alterações e desmonte a imagem. No prompt de comando, digite:
```
Dism /Unmount-Image /mountdir:c:\test\offline /commit
```

Observação

Os aplicativos da Microsoft Store não são executados no modo de auditoria. Para testar sua implantação, execute o Windows e crie um novo perfil de usuário. Para obter mais informações sobre o modo de auditoria, consulte Visão geral do modo de auditoria.

Importante Se você estiver pré-instalando um aplicativo de dispositivo de banda larga móvel, deverá inserir o sim cartão no computador antes de executar a fase especializada do Sysprep. Para obter mais informações sobre a pré-instalação de um aplicativo de dispositivo de banda larga móvel, consulte Pré-instalar os componentes necessários para uma experiência de aplicativo de banda larga móvel.

Atualizar ou remover pacotes

Você pode remover um aplicativo pré-instalado, incluindo a licença e os arquivos de dados personalizados, de uma imagem do Windows usando a ferramenta DISM.exe ou os cmdlets DISM em Windows PowerShell. Você deve remover a versão antiga do aplicativo antes de instalar uma nova.

Remover um aplicativo pré-instalado usando DISM

Abra o Prompt de Comando das Ferramentas de Implantação, instalado com o Windows ADK, com privilégios de administrador. Na tela Iniciar, digite Implantação e Ambiente de Ferramentas de Imagem, clique com o botão direito do mouse no ícone e selecione Executar como Administrador.

Monte a imagem offline para manutenção. No prompt de comando, digite:

Dism /Mount-Image /ImageFile:c:\images\myimage.wim /Index:1 /mountdir:c:\test\offline

Localize o nome completo do pacote do aplicativo que você deseja remover. No prompt de comando, digite:
```
Dism /Image:C:\test\offline /Get-ProvisionedAppxPackages
```

Remova o aplicativo da imagem montada. Por exemplo, no prompt de comando, digite:

Dism /Image:c:\test\offline /Remove-ProvisionedAppxPackage /PackageName:microsoft.devx.appx.app1_1.0.0.0_neutral_en-us_ac4zc6fex2zjp

Se você quiser atualizar o aplicativo, poderá pré-instalar a versão atualizada do aplicativo assinado pela Microsoft Store. Em um prompt de comando, digite:
```
Dism /Image:c:\test\offline /Add-ProvisionedAppxPackage/FolderPath:c:\downloads\appxpackage
```
Salve as alterações e desmonte a imagem. No prompt de comando, digite:
```
Dism /Unmount-Image /mountdir:c:\test\offline /commit
```

Usar arquivos de dados personalizados

Os aplicativos pré-instalados em um computador podem acessar dados personalizados específicos da instalação. Esses dados personalizados são adicionados ao aplicativo durante a pré-instalação e ficam disponíveis em runtime. Os dados personalizados permitem que os desenvolvedores personalizem os recursos e a funcionalidade de um aplicativo, incluindo o fornecimento de recursos de relatório.

Adicionar um arquivo de dados personalizado a uma imagem do Windows

Você deve especificar o arquivo de dados personalizado ao pré-instalar o aplicativo usando a ferramenta DISM e por meio de Windows PowerShell usando o cmdlet Add-AppxProvisionedPackage. O comando a seguir mostra como fazer isso usando a ferramenta DISM:

Dism /Image:C:\test\offline /Add-ProvisionedAppxPackage / FolderPath:f:\Apps\Fabrikam_KnowMyPC /CustomDataPath:f:\Contoso_Promotion.xml

Se já existir um arquivo de dados personalizado no repositório de dados de um aplicativo, por exemplo, se o pacote já tiver sido adicionado à imagem, o arquivo existente será substituído. Se a instalação falhar, o arquivo não será restaurado.

Nota Você pode liberar atualizações para um aplicativo por meio da Microsoft Store sem perder o arquivo de dados personalizado. No entanto, se um usuário excluir o aplicativo, o arquivo de dados personalizado não estará mais disponível, mesmo que o usuário reinstale o aplicativo.

Testar dados personalizados para aplicativos pré-instalados

Os aplicativos pré-instalados em um computador podem acessar dados personalizados específicos da instalação. Esses dados personalizados são adicionados ao aplicativo durante a pré-instalação e ficam disponíveis para o aplicativo em runtime. Os dados personalizados permitem que os desenvolvedores personalizem os recursos e a funcionalidade de um aplicativo, incluindo o fornecimento de recursos de relatório.

O arquivo Custom.data aparece no local instalado do aplicativo. O nome Custom.data é embutido em código e não pode ser modificado. Seu aplicativo pode marcar a existência desse arquivo para determinar se o aplicativo foi pré-instalado no computador. Aqui está um exemplo de como acessar o arquivo Custom.data.

var outputDiv = document.getElementById("CustomData");
Windows.ApplicationModel.Package.current.installedLocation.getFileAsync
     ("microsoft.system.package.metadata\\Custom.data").then(function (file) {
         // Read the file
         Windows.Storage.FileIO.readTextAsync(file).done(function (fileContent) {
            outputDiv.innerHTML = 
                 "App is preinstalled. CustomData contains:<br /><br />"
                 + fileContent;
         },
         function (error) {
             outputDiv.innerText = "Error reading CustomData " + error;
         });
     },
     function (error) {
         outputDiv.innerText = "CustomData was not available. App not preinstalled";
     });

Seu arquivo Custom.data pode incluir qualquer conteúdo e estar em qualquer formato exigido pelo aplicativo. O processo de pré-instalação simplesmente o disponibiliza para seu aplicativo. Os desenvolvedores podem fornecer o arquivo de dados para o parceiro de pré-instalação ou você pode concordar com um formato que permite que o parceiro gere o conteúdo.

Testar seus dados personalizados

Ao criar e depurar seu aplicativo no Microsoft Visual Studio, você não pode acessar o arquivo Custom.data do local instalado do aplicativo porque o aplicativo ainda não está pré-instalado. Você pode simular usando o arquivo Custom.data colocando um arquivo Custom.data de teste no próprio aplicativo e, em seguida, carregando e testando o arquivo local do aplicativo. Para fazer isso, modifique o exemplo de código de:

("microsoft.system.package.metadata\\Custom.data").then(function (file) {

para:

("Custom.data").then(function (file) {

Depois de verificar o formato e o conteúdo do arquivo, você pode alterar o local do arquivo Custom.data para o local final, conforme mostrado no exemplo original acima.

Para testar seu arquivo Custom.data

Abra o Prompt de Comando das Ferramentas de Implantação, instalado com o Windows ADK, com privilégios de administrador. Na tela Iniciar, digite Implantação e Ambiente de Ferramentas de Imagem, clique com o botão direito do mouse no ícone e selecione Executar como Administrador.
Adicione o aplicativo com o arquivo de dados personalizado:
```
dism /online /Add-ProvisionedAppxPackage /PackagePath:.\CustomData_1.0.0.1_AnyCPU_Debug.appx /CustomDataPath:.\Test.txt /SkipLicense
```
Onde /PackagePath:.\CustomData_1.0.0.1_AnyCPU_Debug.appx aponta para o pacote de teste do aplicativo local e onde /CustomDataPath:.\Test.txt aponta para o arquivo Custom.data. Lembre-se de que o nome do arquivo fornecido aqui não é usado depois que os dados são instalados em seu aplicativo.

O aplicativo agora tem um bloco na tela Inicial do computador usado para testar o aplicativo. O aplicativo deve ser capaz de acessar o arquivo Custom.data. Se for necessária uma depuração adicional, anexe um depurador depois de iniciar o aplicativo na tela Inicial .

Nota Talvez seja necessário sair e entrar novamente para ver o aplicativo na tela Inicial .
Depois de terminar de testar seu aplicativo, você deve remover o pacote pré-instalado para continuar usando seu ambiente de desenvolvimento. Para remover o pacote pré-instalado usando Windows PowerShell, você pode usar o cmdlet Get-AppxPackage para fornecer o nome completo do pacote do aplicativo por meio do pipeline para o cmdlet Remove-ProvisionedAppxPackage:

Get-AppxPackage *CustomData* | Remove-ProvisionedAppxPackage

Em que *CustomData* é a parte conhecida do nome do aplicativo

Pré-instalar um aplicativo de dispositivo da Microsoft Store ou um aplicativo de banda larga móvel

Você pode pré-instalar os componentes necessários para um aplicativo de dispositivo da Microsoft Store ou um aplicativo de banda larga móvel usando a plataforma DISM (Gerenciamento e Manutenção de Imagens de Implantação).

Nota Este artigo destina-se aos OEMs, que darão suporte a um aplicativo de dispositivo da Microsoft Store ou ao aplicativo de banda larga móvel em seus dispositivos.

Para cada tipo de aplicativo, duas coisas devem ser pré-instaladas para fornecer o aplicativo de dispositivo da Microsoft Store ou o aplicativo de banda larga móvel correto:

Aplicativo de dispositivo da Microsoft Store, pré-instalação:
1. O pacote de metadados do dispositivo
2. O aplicativo
Aplicativo de banda larga móvel da Microsoft Store, pré-instalação:
1. O pacote de metadados de serviço
2. O aplicativo

Importante Embora os pacotes de metadados e os aplicativos correspondentes sejam analisados imediatamente após a conclusão do processo OOBE, um usuário pode ser capaz de iniciar o aplicativo antes que o pacote de metadados seja analisado. Nesse caso, o usuário verá um erro de acesso negado. Para evitar isso, aplique o pacote de metadados e o aplicativo à imagem do sistema.

Pré-instalar os metadados do dispositivo ou o pacote de metadados de serviço

Para pré-instalar um pacote de metadados de serviço ou metadados de dispositivo

Se você estiver pré-instalando um aplicativo de dispositivo da Microsoft Store, deverá ter adquirido o pacote de metadados do dispositivo. Se você estiver pré-instalando um aplicativo de banda larga móvel, deverá ter adquirido o pacote de metadados do serviço.

Nota Pacotes de metadados de dispositivo e pacotes de metadados de serviço usam a mesma extensão de nome de arquivo (.devicemetadata-ms).
Copie os metadados do dispositivo ou o pacote de metadados de serviço (arquivo devicemetadata-ms) para a imagem do sistema na pasta %ProgramData%\Microsoft\Windows\DeviceMetadataStore . Faça isso de uma das seguintes maneiras:
- Online antes de executar o Sysprep
- Offline depois de executar o Sysprep usando DISM. Para fazer isso:
  1. Monte a imagem offline para manutenção.
```
Dism /Mount-Image /ImageFile:C:\test\images\myimage.wim /index:1 /MountDir:C:\test\offline
```
  2. Copie os arquivos do pacote de metadados para o repositório de metadados do dispositivo da imagem montada. Por exemplo, para copiar o arquivo de pacote de metadados 0ECF2029-2C6A-41AE-9E0A-63FFC9EAD877.devicemetadata-ms para o repositório de metadados do dispositivo, ProgramData\Microsoft\Windows\DeviceMetadataStore:
```
copy 0ECF2029-2C6A-41AE-9E0A-63FFC9EAD877.devicemetadata-ms C:\test\offline\ProgramData\Microsoft\Windows\DeviceMetadataStore
```
  3. Salve as alterações e desmonte a imagem.
```
dism /Unmount-Image /mountdir: c:\test\offline /commit
```
  Para obter mais informações sobre a manutenção de imagens offline, consulte Visão geral do DISM.

Para obter mais informações sobre metadados de serviço, consulte Metadados de serviço.

Pré-instalar o aplicativo de dispositivo da Microsoft Store ou o aplicativo de banda larga móvel

Para pré-instalar o aplicativo de dispositivo da Microsoft Store ou o aplicativo de banda larga móvel

Monte a imagem offline para manutenção.

Dism /Mount-Image /ImageFile:C:\test\images\myimage.wim /index:1 /MountDir:C:\test\offline

Adicione o aplicativo de dispositivo da Microsoft Store ou o aplicativo de banda larga móvel à imagem.
```
dism /Image:<mounted folder> /Add-ProvisionedAppxPackage /FolderPath:<appxpackage path>
```

Salve as alterações e desmonte a imagem.

dism /Unmount-Image /mountdir: c:\test\offline /commit