Personalizar sua imagem do SO de validação usando o GenImage (avançado)

Artigo
06/07/2024

O GenImage oferece uma interface de linha de comando flexível e altamente personalizável para a produção de imagens de SO de validação exatamente para os seus cenários. O Construtor de Imagens do SO de validação utiliza o GenImage, mas cria uma camada de abstração para oferecer um fluxo de trabalho conveniente, mas um tanto limitado, e baseado na interface do usuário. O GenImage tem muito mais capacidade do que o exposto na interface do usuário do Construtor de Imagens do SO de validação, e esta seção detalhará as nuances da geração de uma imagem totalmente personalizável do SO de validação.

Observação

Imagens totalmente personalizadas significam que a imagem do SO de validação criada usando uma lista arbitrária de pacotes de personalização pode resultar em um sistema operacional não funcional.
O GenImage não vai gerar um modelo de solução do Visual Studio.

Processo geral

O processo geral para a criação de uma imagem do SO de validação é o seguinte:

Monte o arquivo ISO do SO de validação em um local específico no sistema de arquivos do computador de técnico.
Inicie um prompt de comando elevado e navegue até a pasta <ISO_ROOT>:\cabs.
[Opcional] Adicione os drivers à imagem do SO de validação.
[Opcional] Crie um arquivo personalizado de configuração de recursos.
[Opcional] Adicione os recursos ou pacotes sob demanda desejados à imagem do SO de validação.
[Opcional] Defina/substitua chaves do Registro na imagem do SO de validação.
[Opcional] Inclua binários/aplicativos personalizados na imagem do SO de validação.
[Opcional] Defina o fuso horário da imagem do SO de validação.

Pacotes de recursos predefinidos

O arquivo ISO do SO de validação contém predefinições do pacote de recursos na pasta <ISO_ROOT>:\GenImage\configs. Esses arquivos .pkg podem ser abertos em um editor de texto para a análise de seu conteúdo. A seção superior desses arquivos contém mais informações sobre o recurso específico.

Criação de um pacote de recursos personalizado

Se as predefinições do pacote de recursos fornecidas no arquivo ISO do SO de validação não forem apropriadas para um cenário, um pacote de recursos personalizado poderá ser facilmente definido seguindo o mesmo formato intuitivo dos arquivos .pkg predefinidos:

Todo conteúdo depois de um caractere # é considerado um comentário.
Uma linha por nome de pacote (.cab) sem a extensão de arquivo. Esses arquivos .cab residem em <ISO_ROOT>:\cabs\neutral e com pacotes de idioma correspondentes em <ISO_ROOT>:\cabs\en-us (se apropriado).
Uma referência a outra definição de recurso a ser incluída usando o formato +include <package_name>.<ext>.

Os pacotes incluídos podem residir no mesmo diretório que o arquivo de definição do pacote personalizado ou podem ser um dos arquivos .pkg fornecidos como parte do arquivo ISO do SO de validação em <ISO_ROOT>:\GenImage\configs.

Observação

Não é necessário especificar um caminho de arquivo para os pacotes incluídos.

A versão wow64 do pacote não deve precisar ser adicionada ao arquivo de configuração. O GenImage incluirá automaticamente a versão wow do pacote, se ela existir.

Observação

Se um pacote (.cab) for listado várias vezes via entrada duplicada no arquivo ou via definição de recurso incluída, o GenImage aplicará esse pacote somente uma vez.

Importante

Alguns recursos têm dependências entre pacotes (cab-to-cab), o que significa que a imagem gerada do SO de validação só funcionará se todos os pacotes necessários estiverem incluídos. Essas dependências não são aplicáveis pelo GenImage, então é possível gerar uma imagem não funcional ou parcialmente funcional do SO de validação ao usar definições de recurso personalizadas.

Especificação da imagem base (`-ImagePath` e `-ImageFile`)

O parâmetro -ImageFile: da linha de comando pode ser usado para informar o nome da imagem base do SO de validação.

Ao trabalhar com o arquivo ISO do SO de validação fornecido, esse parâmetro pode ser ignorado, já que o GenImage assumirá ValidationOS.wim como padrão.

O parâmetro -ImagePath: da linha de comando pode ser usado para informar o caminho da imagem base do SO de validação.

Ao trabalhar com o arquivo ISO do SO de validação fornecido, esse parâmetro pode ser ignorado, já que o GenImage assumirá a raiz de montagem do arquivo ISO como padrão.

Inclusão de recursos (`-PackagesList:`)

O argumento -PackagesList: da linha de comando permite o uso de um ou mais recursos predefinidos ou personalizados, fornecendo o caminho para o arquivo de configuração.

Ao especificar vários arquivos .pkg, use esse parâmetro várias vezes:

-PackagesList:<file1> -PackagesList:<file2> [...]

Como alternativa, use a seguinte sintaxe:

-PackagesList:"<file1>,<file2>[,...]"

Ao usar o último formato, garanta que a lista separada por vírgulas esteja entre aspas duplas.

-PackageList e `-PkgLst: são aliases para -PackagesList:

O GenImage procurará o pacote sob demanda em <ISO_ROOT>:\cabs\neutral e <ISO_ROOT>:\cabs\en-us, a menos que ocorra substituição pelo parâmetro -PackagePath: da linha de comando.

Inclusão de pacotes sob demanda sem utilizar as definições de recurso (`-Packages:`)

O parâmetro -Packages: da linha de comando pode ser utilizado para fornecer uma lista separada por vírgulas dos nomes de pacotes sob demanda a serem incluídos na imagem personalizada do SO de validação. A lista deve estar entre aspas duplas.

O GenImage ainda cuidará da adição das variantes wow64 dos pacotes, por isso não há necessidade de especificá-las usando o parâmetro -Packages:.

Devido ao comprimento dos nomes de pacote, é fácil acabar criando uma linha de comando muito longa usando o parâmetro -Packages:, por isso recomendamos a criação de uma definição de recurso personalizada para a adição de vários pacotes. Para obter detalhes sobre as definições de recurso personalizadas, consulte Criação de um pacote de recursos personalizado.

Substituição do local de pacote padrão (`-PackagePath`)

O parâmetro -PackagePath: da linha de comando pode ser utilizado para informar o caminho para os pacotes sob demanda do SO de validação. No caminho fornecido, deve existir um diretório neutro e um diretório en-us contendo os respectivos arquivos de pacote sob demanda (incluindo as versões wow, se apropriado).

Ao executar o GenImage pelo arquivo ISO do SO de validação, esse parâmetro pode ser ignorado, pois o GenImage assumirá <ISO_ROOT>:\cabs como padrão.

Adicionar drivers .inf à imagem do SO de validação (`-Drivers:` / `-DriversOnly`)

O parâmetro -Drivers: da linha de comando pode ser utilizado para fornecer o caminho para um repositório de drivers específico do dispositivo. O GenImage adicionará recursivamente todos os drivers no caminho especificado.

Se os drivers estiverem estruturados em <WinVOS_Root>\Drivers\<my_device>, o parâmetro -HW:<my_device> da linha de comando poderá ser utilizado como atalho para incluir esses drivers. Para obter mais detalhes sobre WinVOS_Root, consulte “Especificação do caminho da imagem personalizada do SO de validação”.

Quando os drivers forem incluídos na imagem personalizada do SO de validação, o GenImage adicionará automaticamente o pacote de recursos <ISO_ROOT>\GenImage\configs\usb.pkg a fim de garantir que os drivers tenham os drivers de classe mais básica para funcionarem. No entanto, o uso da opção -SkipDeviceFeatures da linha de comando anulará esse comportamento.

O uso da opção -DriversOnly da linha de comando permite a adição de drivers sem precisar incluir nenhum recurso ou pacote individual.

Seleção do destino de inicialização da imagem do SO de validação (`-x`)

É possível gerar a imagem WIM personalizada do SO de validação para dois cenários de uso diferentes: aplicação da imagem diretamente ao disco rígido interno de um dispositivo de destino (inicialização por C:) ou uso do arquivo .wim gerado para substituição de boot.wim em uma unidade USB do WinPE (inicialização de X:).

Para acomodar ambos os cenários, o envio do ValidationOS.wim base na raiz do arquivo ISO contém duas partições: a partição 1 é utilizada para compatibilidade com a recuperação para C:, enquanto a partição 2 é usada para oferecer suporte aos cenários USB (inicialização de X:).

Por padrão, o GenImage produzirá o ValidationOS.wim para que seja recuperado no disco rígido interno de um computador de destino (inicialização de C:).

O parâmetro -x da linha de comando pode ser utilizado para gerar uma imagem que ofereça suporte ao cenário de inicialização da unidade USB por X:.

Observação: -usb é um alias para o parâmetro -x.

Inclusão de arquivos personalizados na imagem (`-AddedSW` e `-AddedSWTargetDir`)

Todos os arquivos no caminho especificado para o parâmetro -AddedSW: da linha de comando serão copiados para a imagem personalizada do SO de validação. Por padrão, o conteúdo desse caminho será copiado em <WIM_ROOT>:\Programs\<folder>, em que “folder” é o nome da pasta a ser incluída. Por exemplo, -AddedSW:D:\Test\MyFiles será copiado em <WIM_ROOT>:\Programs\MyFiles.

O parâmetro -AddedSW pode ser especificado diversas vezes apontando para locais diferentes.

O parâmetro -AddedSWTargetDir: da linha de comando pode ser utilizado para substituir o local de destino pela imagem personalizada do SO de validação.

A opção -NoPackages da linha de comando pode ser utilizada para realizar o pós-processamento de uma imagem já personalizada do SO de validação e adicionar arquivos em uma etapa separada.

Alteração do Registro (`-RegistryImport:`)

O parâmetro -RegistryImport: da linha de comando pode ser utilizado para aplicar um arquivo .reg padrão do Editor do Registro do Windows versão 5.00 à imagem personalizada do SO de validação.

A opção -NoPackages da linha de comando pode ser utilizada para realizar o pós-processamento de uma imagem já personalizada do SO de validação e personalizar o Registro em uma etapa separada.

Alteração do fuso horário (`-TimeZone:`)

O parâmetro -TimeZone: da linha de comando pode ser utilizado para modificar o fuso horário da imagem personalizada do SO de validação. A cadeia de caracteres fornecida precisa ser um fuso horário válido do Windows, senão o GenImage falhará.

Especificação do caminho da imagem personalizada do SO de validação (`-OutPath:` / `-WinVOS_Root:`)

Ao executar o GenImage do arquivo ISO do SO de validação montado, ele produzirá sua saída (e todo o conteúdo intermediário) no diretório C:\WinVOS\out\<date>-<time> (por exemplo, C:\WinVOS\out\240116-1242). Esse comportamento pode ser alterado utilizando os parâmetros -OutPath: ou -WinVOS_Root: da linha de comando. A seguir estão as diferenças entre eles:

O parâmetro -OutPath: especificará o local exato da saída, portanto, o WIM personalizado do SO de validação e todo o conteúdo intermediário serão criados nesse diretório.

Importante

Usar o mesmo -OutPath: para uma execução subsequente do GenImage poderá resultar em efeitos colaterais inesperados.

O parâmetro -WinVOS_Root: criará uma subpasta out\<date>-<time> no diretório especificado.

Dica

Prefira usar o parâmetro -WinVOS_Root: em vez do parâmetro -OutPath: para evitar conflitos entre arquivos temporários ou problemas de arquivos .wim esquecidos montados.

Por padrão, o GenImage será utilizado -OutPath: para montar o WIM para fins de processamento. O parâmetro -MountDir: da linha de comando pode ser utilizado para substituir o local desse ponto de montagem intermediário.

Limpeza de WIMs montados e potencialmente travados (`-CleanUp`)

Se o GenImage for interrompido ou um WIM montado estiver travado, o parâmetro -CleanUp da linha de comando poderá ser utilizado em uma tentativa de limpeza automática.

Esse parâmetro só pode ser utilizado sozinho.

Ignorar a confirmação do processamento da imagem (`-NoWait`)

O parâmetro -NoWait da linha de comando pode ser utilizado para ignorar a confirmação depois que a opção de geração da imagem é exibida e prosseguir com o processamento da imagem.

Saída detalhada

O parâmetro -v da linha de comando pode ser utilizado para mudar o nível de registro em log do GenImage para detalhado.

O uso dessa opção gerará muita saída, por isso recomendamos o redirecionamento da saída padrão para um arquivo.

Mostrar o uso de scripts

O parâmetro -h da linha de comando pode ser utilizado para exibir informações sobre o uso de scripts.

-? e -help são aliases para -h.

Exemplos do GenImage

Supondo que o arquivo ISO do SO de validação esteja montado em J:, veja a seguir alguns exemplos para geração de WIMs personalizados do SO de validação.

Adicionar recurso multimídia sem nenhum driver usando padrões ISO

J:\GenImage>GenImage.cmd -PackagesList:J:\GenImage\configs\multimedia.pkg

Adicionar recursos multimídia e Wi-Fi com drivers usando padrões ISO e ignorando a confirmação

Supondo que os drivers estejam em D:\Drivers\MyDevice:

J:\GenImage>GenImage.cmd -PackagesList:J:\GenImage\configs\multimedia.pkg -PackagesList:J:\GenImage\configs\wifi.pkg -drivers:D:\Drivers\MyDevice -NoWait

J:\GenImage>GenImage.cmd -PackagesList:"J:\GenImage\configs\multimedia.pkg,J:\GenImage\configs\wifi.pkg" -drivers:D:\Drivers\MyDevice -NoWait

Adicionar recurso de provisionamento sem nenhum driver utilizando um WIM personalizado anteriormente

J:\GenImage>GenImage.cmd -PackagesList:J:\GenImage\configs\provisioning.pkg -ImagePath:C:\WinVOS\out\240116-1530

Adicionar recurso de depuração com drivers e incluir Python

Supondo que o Python seja extraído em D:\Staging\Python e os drivers estejam em D:\Drivers\MyDevice:

J:\GenImage>GenImage.cmd -PackagesList:J:\GenImage\configs\debug.pkg -ImagePath:J:\ -Drivers:D:\Drivers\MyDevice -AddedSW:D:\Staging\Python

Uso total do GenImage.cmd

O GenImage.cmd é altamente personalizável para oferecer suporte a diversos cenários personalizados. Aqui está a lista completa de parâmetros necessários, além de alguns exemplos de uso:

            [-Packages:|-PackagesList:|-DriversOnly|-NoPackages]
            [-Drivers:|-HW]
            [-WinVOS_Root:] [-MountDir:]
            [-wim|-vhd|-vhdx] [-usb|-x] [-inc]
            [-TimeZone:]
            [-AddedSW: [-AddedSWTargetDir:]]
            [-RegistryImport:] [-StartupCommand:]
            [-NoWait] [-v]
            NOTE: Running From ISO: [YES]
            -?|-h|-help This screen

-ImageFile:                             <file_name> File name of the image file to be processes.
                                        Defaults to ValidationOS.wim
                                        -wim, -vhd and -vhdx are ignored

-ImagePath:<file_path>                  Path to the image file to be processed.
                                        Default/Current: [J:\]

-PackagePath:<path>                     Path to the cab files to be added to the image.
                                        Defaults to J:\cab or J:\Packages

                                        Neutral and localized packages are placed into their respective
                                        folders under "cab": "neutral" and "en-us".

-OutPath:<path>                         Location of the generated image
                                        Default/Current: [C:\WinVOS\out\240116-1640]

-Packages:<list>                        Comma or space separated list of packages.
                                        Use double quotes around the list.

-PackagesList|PackageList|PkgLst:<file> Use a text file to specify which 
                                        packages will be added to the image
                                        One package name per line, use # for comments

-NoPackages                             Do not include any packages

-DriversOnly                            Do not include any packages, add drivers only
                                        Requires specifying either -Drivers or -HW, but not both

-Drivers:<path>                         Path to drivers
                                        If neither -HW nor -Drivers are not specified
                                        no drivers will be added to the image.
                                        If -HW was used defaults to C:\WinVOS\Drivers\%HW%

-HW:<hardware>                          Hardware variant used for driver installation.
                                        If neither -HW nor -Drivers are specified, no
                                        drivers will be added to the image.

                                        The value specified for this parameter will be appended
                                        to [C:\WinVOS\Drivers]

-SkipDeviceFeatures                     Do NOT automatically include USB support when
                                        drivers are added to the image

-WinVOS_Root:<path>                     Root of the directory structure to process
                                        Default/Current: [C:\WinVOS]

-MountDir:<path>                        Path to mount the image to for processing
                                        Default/Current: C:\WinVOS\out\240116-1640\mnt

-wim                                    Assume the image is a wim file
                                        This is default extension unless -ImageFile, -vhd(x) are specified.

-vhd|-vhdx                              Assume the image is a vhdx file
                                        .wim is default extension unless -ImageFile is specified.

-usb|-x                                 Assume USB boot and set the image index to 2 during mount
                                        Default image index is 1

-TimeZone:<time zone>                   Sets the time zone of the image to the specified value.
                                        NOTE: The validity of this setting is not checked.

-AddedSW:<path>                         Files and folders under path will be copied into the
                                        generated image.

                                        Default target location is \Programs, can be overriden with
                                        -AddedSWTargetDir

-AddedSWTargetDir:<path>                Target - in image - path to copy the contents specified by AddedSW.
                                        Default is \Programs

-RegistryImport:<file>                  Path the a .reg file to be imported into the generated image.
                                        This file can multiple hives under HKLM. Supported hives:
                                        COMPONENTS DEFAULT DRIVERS SAM SECURITY SOFTWARE SYSTEM

-StartupCommand:<file>                  Path the an executablefile to be used as the ValidationOS Shell
                                        On boot this file will be executed first. If the file does not spawn
                                        a new CMD window, the shell will be this new executable.

-inc|-incremental                       Do not restore the package from backup

-CleanUp                                Clean up lingering mounted images.
                                        Will attempt to clean up the mounted into /MountDir.
                                        If /MountDir is not specified it will attempt to clean up
                                        any corrupted and/or prevously mounted images.

                                        NOTE: Not using /MountDir with /Cleanup is a drastic cleaup tactic.

-NoWait                                 Don't pause after displaying image generation settings.

-v                                      Verbose logging

Examples:

* Add all packages in the default "cab" folder under the default package path [J:\cabs] to the default image
  file [ValidationOS.wim] under the default path [J:\] without including drivers:

    GenImage

* Add all packages under the "cab" folder to a ValidationOS.wim and include the drivers for "SP6"

    GenImage -ImageFile:ValidationOS.wim -ImagePath:C:\WinVOS\release\25108.1001.220429-1329\amd64fre -HW:SP6

* Add packages specified in custom.pkg under the "cab" folder to a ValidationOS.vhdx without including drivers:

    GenImage -ImagePath:C:\WinVOS\release\25108.1001.220429-1329\amd64fre -vhdx -PackagesList:custom.pkg

* Incrementally add "Microsoft-WinVOS-NetFx45-Package" to ValidationOS.wim. The package is located in "cab" under the specified image path folder.

    GenImage -inc -ImageFile:ValidationOS.wim -ImagePath:C:\WinVOS\release\25108.1001.220429-1329\amd64fre -Packages:"Microsoft-WinVOS-NetFx45-Package"

Observação sobre como usar a versão correspondente do conjunto de ferramentas dism para a criação de imagens

Ao executar o GenImage.cmd pelo arquivo ISO montado, a preferência do script será por usar o dism.exe que é fornecido no arquivo ISO com o GenImage.cmd. Essa é a versão recomendada do dism para qualquer tarefa de manipulação de imagem porque corresponde à versão da ferramenta utilizada para criar o ValidationOS.wim enviado e os pacotes opcionais.

(Experimental) Adicionar suporte a WWAN

Cuidado

Este recurso é experimental e oferece suporte muito limitado.

O SO de validação introduziu suporte antecipado a WWAN a fim de fornecer interação com o modem por meio de comandos AT.

É necessária a adição de dois à composição da imagem: Microsoft-WinVOS-WWAN-Package e Microsoft-WinVOS-PnP-Settings.

Esse cenário não é compatível com o GenImage, o que significa que os pacotes precisam ser aplicados usando o dism.exe fornecido no arquivo ISO do SO de validação. Use o dism.exe de <ISO_ROOT>:\GenImage\Tools\DISM\%PROCESSOR_ARCHITECTURE%, em que PROCESSOR_ARCHITECTURE é a arquitetura do processador do computador do técnico (por exemplo, AMD64).

Compartilhar via

Personalizar sua imagem do SO de validação usando o GenImage (avançado)

Processo geral

Pacotes de recursos predefinidos

Criação de um pacote de recursos personalizado

Especificação da imagem base (`-ImagePath` e `-ImageFile`)

Inclusão de recursos (`-PackagesList:`)

Inclusão de pacotes sob demanda sem utilizar as definições de recurso (`-Packages:`)

Substituição do local de pacote padrão (`-PackagePath`)

Adicionar drivers .inf à imagem do SO de validação (`-Drivers:` / `-DriversOnly`)

Seleção do destino de inicialização da imagem do SO de validação (`-x`)

Inclusão de arquivos personalizados na imagem (`-AddedSW` e `-AddedSWTargetDir`)

Alteração do Registro (`-RegistryImport:`)

Alteração do fuso horário (`-TimeZone:`)

Especificação do caminho da imagem personalizada do SO de validação (`-OutPath:` / `-WinVOS_Root:`)

Limpeza de WIMs montados e potencialmente travados (`-CleanUp`)

Ignorar a confirmação do processamento da imagem (`-NoWait`)

Saída detalhada

Mostrar o uso de scripts

Exemplos do GenImage

Adicionar recurso multimídia sem nenhum driver usando padrões ISO

Adicionar recursos multimídia e Wi-Fi com drivers usando padrões ISO e ignorando a confirmação

Adicionar recurso de provisionamento sem nenhum driver utilizando um WIM personalizado anteriormente

Adicionar recurso de depuração com drivers e incluir Python

Uso total do GenImage.cmd

Observação sobre como usar a versão correspondente do conjunto de ferramentas dism para a criação de imagens

(Experimental) Adicionar suporte a WWAN

Recursos adicionais

Compartilhar via

Personalizar sua imagem do SO de validação usando o GenImage (avançado)

Processo geral

Pacotes de recursos predefinidos

Criação de um pacote de recursos personalizado

Especificação da imagem base (-ImagePath e -ImageFile)

Inclusão de recursos (-PackagesList:)

Inclusão de pacotes sob demanda sem utilizar as definições de recurso (-Packages:)

Substituição do local de pacote padrão (-PackagePath)

Adicionar drivers .inf à imagem do SO de validação (-Drivers: / -DriversOnly)

Seleção do destino de inicialização da imagem do SO de validação (-x)

Inclusão de arquivos personalizados na imagem (-AddedSW e -AddedSWTargetDir)

Alteração do Registro (-RegistryImport:)

Alteração do fuso horário (-TimeZone:)

Especificação do caminho da imagem personalizada do SO de validação (-OutPath: / -WinVOS_Root:)

Limpeza de WIMs montados e potencialmente travados (-CleanUp)

Ignorar a confirmação do processamento da imagem (-NoWait)

Saída detalhada

Mostrar o uso de scripts

Exemplos do GenImage

Adicionar recurso multimídia sem nenhum driver usando padrões ISO

Adicionar recursos multimídia e Wi-Fi com drivers usando padrões ISO e ignorando a confirmação

Adicionar recurso de provisionamento sem nenhum driver utilizando um WIM personalizado anteriormente

Adicionar recurso de depuração com drivers e incluir Python

Uso total do GenImage.cmd

Observação sobre como usar a versão correspondente do conjunto de ferramentas dism para a criação de imagens

(Experimental) Adicionar suporte a WWAN

Recursos adicionais

Especificação da imagem base (`-ImagePath` e `-ImageFile`)

Inclusão de recursos (`-PackagesList:`)

Inclusão de pacotes sob demanda sem utilizar as definições de recurso (`-Packages:`)

Substituição do local de pacote padrão (`-PackagePath`)

Adicionar drivers .inf à imagem do SO de validação (`-Drivers:` / `-DriversOnly`)

Seleção do destino de inicialização da imagem do SO de validação (`-x`)

Inclusão de arquivos personalizados na imagem (`-AddedSW` e `-AddedSWTargetDir`)

Alteração do Registro (`-RegistryImport:`)

Alteração do fuso horário (`-TimeZone:`)

Especificação do caminho da imagem personalizada do SO de validação (`-OutPath:` / `-WinVOS_Root:`)

Limpeza de WIMs montados e potencialmente travados (`-CleanUp`)

Ignorar a confirmação do processamento da imagem (`-NoWait`)