Настройка образа ОС проверки с помощью GenImage (Дополнительно)

Статья
12/21/2024

GenImage предоставляет гибкий и высоко настраиваемый интерфейс командной строки для создания образов ОС для валидации, точно под ваши сценарии. Создатель образов ОС для проверки использует GenImage, но создает слой абстракции для удобного, но несколько ограниченного рабочего процесса на основе пользовательского интерфейса. GenImage может гораздо больше, чем то, что предоставляется в пользовательском интерфейсе построителя образов Validation OS, и в этом разделе подробно описаны нюансы создания полностью настраиваемого образа Validation OS.

Заметка

Полностью настраиваемые образы означают, что образ операционной системы проверки, созданный с помощью произвольного списка пакетов настройки, может привести к нефункциональным операционным системам.
GenImage не создаст шаблон решения Visual Studio.

Общий процесс

Общий процесс создания образа ОС проверки приведен ниже.

Подключите ISO-файл операционной системы Validation в определенное место на файловой системе ПК техника.
Запустите командную строку с повышенными привилегиями и перейдите в папку <ISO_ROOT>:\cabs;
[необязательно] добавить драйверы в образ ОС проверки;
[необязательно] создать файл конфигурации пользовательских компонентов;
[необязательно] добавить необходимые функции или пакеты по запросу в образ ОС проверки;
[Необязательно] задать или переопределить ключи реестра в образе Валидационной ОС.
[необязательно] включать пользовательские бинарные файлы и приложения в образ операционной системы для проверки;
[необязательно] задать часовой пояс образа ОС проверки;

Предопределенные пакеты компонентов

ISO-код ОС проверки содержит предварительно определенные определения пакетов компонентов в папке <ISO_ROOT>:\GenImage\configs. Эти .pkg файлы можно открыть в текстовом редакторе для изучения их содержимого. В верхнем разделе этих файлов содержатся дополнительные сведения о конкретной функции.

Создание пользовательского пакета компонентов

Если предопределенные пакеты функций, указанные в ISO-образе операционной системы Validation OS, не подходят для данного сценария, можно легко определить собственный пакет функций, следуя тому же удобному для пользователя формату, что и предопределенные .pkg файлы:

Что-нибудь после # считается комментарием.
Одна строка для каждого имени пакета (.cab) без расширения файла. Эти кабины находятся в <ISO_ROOT>:\cabs\neutral и соответствуют языковым пакетам в <ISO_ROOT>:\cabs\en-us (при необходимости).
Некоторые .cab файлы находятся в вложенных папках в <ISO_ROOT>:\cabs, например <ISO_ROOT>:\cabs\Experimental. Структура этих каталогов соответствует тому же шаблону, что и корневой каталог, а файлы .cab помещаются в вложенные папки neutral или en-us. Чтобы ссылаться на эти пакеты в пользовательском пакете компонентов, просто укажите имя подкаталога после имени пакета, разделенного пробелом и заключенного в квадратные скобки. Например, Microsoft-WinVOS-PnP-Settings-Package [Experimental]
Ссылка на другое определение функции, включаемое с помощью формата +include <package_name>.<ext>.

Включенные пакеты могут находиться либо в том же каталоге, что и файл определения пользовательского пакета, либо они могут быть одним из файлов .pkg, предоставляемых в составе ISO диска операционной системы для валидации под <ISO_ROOT>:\GenImage\configs.

Заметка

Нет необходимости указывать путь к файлу для включенных пакетов. Не включайте версию пакета wow64. GenImage автоматически включает версию пакета wow, если она существует.

При запуске GenImage -packagepath следует установить в каталог CAB-файлов, чтобы GenImage автоматически интегрировал определенные пакеты, вне зависимости от того, находятся ли пакеты в подпапке или в корневом каталоге CAB-файлов.

Пример пользовательского пакета компонентов:

# Feature: Example
# Description: All packages are located in subdirectories
#
Microsoft-OneCore-TAEF-Package  [Test]
Microsoft-WinVOS-PnP-Settings-Package [Experimental]

Заметка

Если пакет (.cab) отображается несколько раз с помощью повторяющихся записей в файле или через включенное определение функции, GenImage будет применять этот пакет только один раз.

Важный

Некоторые функции имеют зависимости между пакетами (cab-to-cab), что означает, что созданный образ ОС валидации не будет корректно функционировать, если не включены все необходимые пакеты. Эти зависимости не применяются GenImage, поэтому при использовании пользовательских определений функций можно создать нефункциональный или частично функциональный образ ОС проверки.

Указание базового образа (`-ImagePath` и `-ImageFile`)

Параметр командной строки -ImageFile: можно использовать для предоставления имени базового образа ОС проверки.

При работе с предоставленным ISO-файлом ОС проверки этот параметр можно пропустить, так как GenImage по умолчанию будет ValidationOS.wim.

Параметр командной строки -ImagePath: можно использовать для предоставления пути к базовому образу ОС проверки.

При работе с предоставленным ISO-файлом Validation OS этот параметр можно пропустить, так как GenImage по умолчанию будет использовать корневой каталог подключения ISO.

Включение функций (`-PackagesList:`)

Аргумент командной строки -PackagesList позволяет использовать одну или несколько предопределенных или пользовательских функций, предоставив путь к файлу конфигурации.

При указании нескольких .pkg файлов используйте этот параметр несколько раз:

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

или используйте следующий синтаксис:

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

При использовании последнего формата убедитесь, что разделенный запятыми список заключен в двойные кавычки.

-PackageList и "-PkgLst: являются псевдонимами для -PackagesList:

GenImage будет искать пакет по запросу под <ISO_ROOT>:\cabs\neutral и <ISO_ROOT>:\cabs\en-us, если это не переопределено параметром командной строки -PackagePath.

Включение пакетов по запросу без использования определений функций (`-Packages:`)

Параметр командной строки -Packages: можно использовать для предоставления разделенного запятыми списка имен пакетов по запросу, которые будут включены в настраиваемый образ ОС проверки. Список должен быть заключен в двойные кавычки.

Добавление вариантов пакетов wow64 всё ещё будет осуществляться с помощью GenImage, нет необходимости указывать их с помощью параметра -Packages:.

Из-за длины имен пакетов легко создать очень длинную командную строку с помощью параметра -Packages:, поэтому рекомендуется создать пользовательское определение функции для добавления нескольких пакетов. Дополнительные сведения о определениях настраиваемых компонентов см. в статье "Создание пользовательского пакета компонентов".

Переопределение расположения пакета по умолчанию (`-PackagePath`)

Параметр командной строки -PackagePath: можно использовать для предоставления пути к пакетам ОС проверки по запросу. В соответствии с предоставленным путем нейтральный каталог и en-us каталог должны существовать, содержащие соответствующие файлы пакетов по требованию (включая версии wow, если это применимо).

При запуске GenImage из ISO образа операционной системы валидации этот параметр можно пропустить, так как GenImage будет использовать <ISO_ROOT>:\cabsпо умолчанию.

Добавьте драйверы INF в образ ОС проверки (`-Drivers:` / `-DriversOnly`)

Параметр командной строки -Drivers: можно использовать для предоставления пути к конкретному репозиторию драйверов устройства. GenImage рекурсивно добавит все драйверы в указанный путь.

Если драйверы структурированы в <WinVOS_Root>\Drivers\<my_device>,, параметр командной строки -HW:<my_device> может использоваться как ярлык для включения этих драйверов. Дополнительные сведения о WinVOS_Root см. в разделе "Указание пути к настроенному образу ОС валидации".

Если драйверы включены в настроенный образ Validation OS, GenImage автоматически добавит пакет функций <ISO_ROOT>\GenImage\configs\usb.pkg, чтобы обеспечить наличие наиболее базовых классов драйверов для их работы. Это поведение, однако, можно переопределить, используя параметр командной строки -SkipDeviceFeatures.

Использование коммутатора командной строки -DriversOnly позволяет добавлять драйверы без включения функций или отдельных пакетов.

Выбор цели загрузки образа ОС для валидации (`-x`)

Настраиваемый образ WIM операционной системы проверки можно создать для назначения двух различных сценариев использования: примените образ непосредственно к внутреннему жесткому диску целевого устройства (загрузка из C:) или используйте созданный WIM-файл для замены boot.wim на USB-накопителе WinPE (загрузка из X:).

Для учета обоих сценариев, содержимое base ValidationOS.wim в корне ISO содержит два раздела: раздел 1 используется для совместимости с восстановлением на C:, а раздел 2 для поддержки сценариев USB (загрузка с X:).

По умолчанию GenImage создает validationOS.wim для восстановления на внутреннем жестком диске целевого компьютера (загрузка из C:).

Параметр командной строки -x можно использовать для создания образа, поддерживающего USB-диск для загрузки в сценарии X:.

Примечание. -usb является псевдонимом параметра -x.

Включение пользовательских файлов в изображение (`-AddedSW` и `-AddedSWTargetDir`)

Все файлы, указанные для параметра командной строки -AddedSW:, будут скопированы в настроенный образ ОС проверки. По умолчанию содержимое этого пути будет скопировано в <WIM_ROOT>:\Programs\<folder>, где "папка" обозначает имя папки, которая будет включена. Например, -AddedSW:D:\Test\MyFiles будет скопировано в <WIM_ROOT>:\Programs\MyFiles.

-AddedSW можно указать несколько раз, указывая на разные расположения.

Параметр командной строки -AddedSWTargetDir: можно использовать для переопределения целевого расположения в настраиваемом образе Проверочной ОС.

Параметр командной строки -NoPackages можно использовать для последующей обработки уже настроенного образа операционной системы Validation и добавления файлов в качестве отдельного шага.

Изменение реестра (`-RegistryImport:`)

Параметр командной строки -RegistryImport: можно использовать для применения стандартного файла редактора реестра Windows версии 5.00 .reg к настроенного образа ОС проверки.

Параметр командной строки -NoPackages можно использовать для дополнительной обработки уже настроенного образа Validation OS и настройки реестра как отдельного шага.

Изменение часового пояса (`-TimeZone:`)

Параметр командной строки -TimeZone: можно использовать для изменения часового пояса настраиваемого образа ОС проверки. Указанная строка должна быть допустимым часовой поясом Windows, в противном случае GenImage завершится ошибкой.

Указание пути настраиваемого образа ОС проверки (`-OutPath:` / `-WinVOS_Root:`)

При запуске GenImage из подключенного ISO-образа операционной системы для валидации выходные данные (и все промежуточные данные) по умолчанию будут создаваться в каталоге C:\WinVOS\out\<date>-<time> (например, C:\WinVOS\out\240116-1242). Это поведение можно изменить, но с помощью -OutPath: или параметров командной строки -WinVOS_Root:. Разница между этими двумя заключается в следующем:

-OutPath: укажет точное расположение выходных данных, поэтому в этом каталоге будет создана настроенная операционная система проверки WIM и все промежуточное содержимое.

Важный

Использование того же -OutPath: для последующего выполнения GenImage может привести к непредвиденным побочным эффектам.

-WinVOS_Root: создаст вложенную папку out\<date>-<time> в указанном каталоге.

Совет

Предпочтительно использовать -WinVOS_Root: вместо -OutPath:, чтобы избежать конфликтов с временными файлами или оставленными смонтированными вим-файлами.

По умолчанию GenImage будет использовать -OutPath: для монтирования WIM в целях обработки. Параметр командной строки -MountDir: можно использовать для переопределения расположения этой промежуточной точки подключения.

Очистка потенциально застрявших подключенных WIM (`-CleanUp`)

Если GenImage прерывается или подключенный WIM зависает, параметр командной строки -CleanUp можно задействовать для попытки автоматической очистки.

Этот параметр можно использовать только самостоятельно.

Пропустить подтверждение обработки изображений (`-NoWait`)

Параметр командной строки -NoWait можно использовать для пропуска подтверждения после отображения параметра создания изображения и выполнения обработки изображений.

Подробный вывод

Параметр командной строки -v можно использовать для изменения уровня ведения журнала GenImage на подробный.

При использовании этого переключателя будет создано много выходных данных, и рекомендуется перенаправить стандартный вывод в файл.

Отображение использования скрипта

Параметр командной строки -h можно использовать для отображения сведений об использовании скрипта.

-? и -help — это псевдонимы для -h

Примеры GenImage

При условии, что ISO-образ Validation OS подключен к J:, ниже представлены некоторые примеры для создания настраиваемых WIM-файлов Validation OS.

Добавить мультимедийную функцию без драйверов, используя стандартные настройки ISO

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

Добавьте мультимедиа и возможности Wi-Fi с драйверами, использовать стандартные настройки ISO, пропуская подтверждение

Предполагая, что драйверы помещаются в 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

Добавление функции подготовки без драйверов с использованием ранее настроенных WIM

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

Добавление функции отладки с драйверами и включение Python

Предполагая, что Python извлекается в D:\Staging\Python, и драйверы помещаются в D:\Drivers\MyDevice

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

Полное использование GenImage.cmd

GenImage.cmd очень настраивается для поддержки нескольких пользовательских сценариев. Ниже приведен полный список параметров, которые он принимает, а также несколько примеров использования:

            [-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"

Обратите внимание на необходимость использования аналогичной версии набора инструментов Dism для создания образа

При запуске GenImage.cmd из подключенного ISO скрипт будет предпочитать использовать dism.exe, которая поставляется на ISO вместе с GenImage.cmd. Это рекомендуемая версия dism для всех задач, связанных с обработкой изображений, так как она соответствует версии средства, используемой для создания поставляемого ValidationOS.wim и дополнительных пакетов.

(Экспериментальный) Добавление поддержки WWAN

Осторожность

Это экспериментальная функция с очень ограниченной поддержкой.

Операционная система проверки представила раннюю поддержку WWAN, чтобы обеспечить взаимодействие с модемом с помощью команд AT.

В состав изображения необходимо добавить два пакета: Microsoft-WinVOS-WWAN-Package и Microsoft-WinVOS-PnP-Settings.

Этот сценарий не поддерживается GenImage, то есть пакеты должны применяться с помощью предоставленных dism.exe на ISO операционной системы проверки. Обязательно используйте dism.exe из <ISO_ROOT>:\GenImage\Tools\DISM\%PROCESSOR_ARCHITECTURE%, где PROCESSOR_ARCHITECTURE — это архитектура процессора компьютера технического специалиста (например, AMD64).

Поделиться через

Настройка образа ОС проверки с помощью GenImage (Дополнительно)

Общий процесс

Предопределенные пакеты компонентов

Создание пользовательского пакета компонентов

Указание базового образа (`-ImagePath` и `-ImageFile`)

Включение функций (`-PackagesList:`)

Включение пакетов по запросу без использования определений функций (`-Packages:`)

Переопределение расположения пакета по умолчанию (`-PackagePath`)

Добавьте драйверы INF в образ ОС проверки (`-Drivers:` / `-DriversOnly`)

Выбор цели загрузки образа ОС для валидации (`-x`)

Включение пользовательских файлов в изображение (`-AddedSW` и `-AddedSWTargetDir`)

Изменение реестра (`-RegistryImport:`)

Изменение часового пояса (`-TimeZone:`)

Указание пути настраиваемого образа ОС проверки (`-OutPath:` / `-WinVOS_Root:`)

Очистка потенциально застрявших подключенных WIM (`-CleanUp`)

Пропустить подтверждение обработки изображений (`-NoWait`)

Подробный вывод

Отображение использования скрипта

Примеры GenImage

Добавить мультимедийную функцию без драйверов, используя стандартные настройки ISO

Добавьте мультимедиа и возможности Wi-Fi с драйверами, использовать стандартные настройки ISO, пропуская подтверждение

Добавление функции подготовки без драйверов с использованием ранее настроенных WIM

Добавление функции отладки с драйверами и включение Python

Полное использование GenImage.cmd

Обратите внимание на необходимость использования аналогичной версии набора инструментов Dism для создания образа

(Экспериментальный) Добавление поддержки WWAN

Дополнительные ресурсы

Поделиться через

Настройка образа ОС проверки с помощью GenImage (Дополнительно)

Общий процесс

Предопределенные пакеты компонентов

Создание пользовательского пакета компонентов

Указание базового образа (-ImagePath и -ImageFile)

Включение функций (-PackagesList:)

Включение пакетов по запросу без использования определений функций (-Packages:)

Переопределение расположения пакета по умолчанию (-PackagePath)

Добавьте драйверы INF в образ ОС проверки (-Drivers: / -DriversOnly)

Выбор цели загрузки образа ОС для валидации (-x)

Включение пользовательских файлов в изображение (-AddedSW и -AddedSWTargetDir)

Изменение реестра (-RegistryImport:)

Изменение часового пояса (-TimeZone:)

Указание пути настраиваемого образа ОС проверки (-OutPath: / -WinVOS_Root:)

Очистка потенциально застрявших подключенных WIM (-CleanUp)

Пропустить подтверждение обработки изображений (-NoWait)

Подробный вывод

Отображение использования скрипта

Примеры GenImage

Добавить мультимедийную функцию без драйверов, используя стандартные настройки ISO

Добавьте мультимедиа и возможности Wi-Fi с драйверами, использовать стандартные настройки ISO, пропуская подтверждение

Добавление функции подготовки без драйверов с использованием ранее настроенных WIM

Добавление функции отладки с драйверами и включение Python

Полное использование GenImage.cmd

Обратите внимание на необходимость использования аналогичной версии набора инструментов Dism для создания образа

(Экспериментальный) Добавление поддержки WWAN

Дополнительные ресурсы

Указание базового образа (`-ImagePath` и `-ImageFile`)

Включение функций (`-PackagesList:`)

Включение пакетов по запросу без использования определений функций (`-Packages:`)

Переопределение расположения пакета по умолчанию (`-PackagePath`)

Добавьте драйверы INF в образ ОС проверки (`-Drivers:` / `-DriversOnly`)

Выбор цели загрузки образа ОС для валидации (`-x`)

Включение пользовательских файлов в изображение (`-AddedSW` и `-AddedSWTargetDir`)

Изменение реестра (`-RegistryImport:`)

Изменение часового пояса (`-TimeZone:`)

Указание пути настраиваемого образа ОС проверки (`-OutPath:` / `-WinVOS_Root:`)

Очистка потенциально застрявших подключенных WIM (`-CleanUp`)

Пропустить подтверждение обработки изображений (`-NoWait`)