Personnalisez votre image Validation OS en utilisant GenImage (Avancé)
GenImage fournit une interface en ligne de commande flexible et hautement personnalisable pour produire des images Validation OS adaptées exactement à vos scénarios. Validation OS Image Builder utilise GenImage, mais il crée une couche d’abstraction pour un flux de travail pratique basé sur l’interface utilisateur, mais quelque peu limité. GenImage est capable de bien plus que ce qui est exposé dans l’interface utilisateur de Validation OS Image Builder, et cette rubrique détaille les nuances de la génération d’une image Validation OS entièrement personnalisable.
Remarque
Les images entièrement personnalisées signifient que l’image Validation OS créée en utilisant une liste arbitraire de packages de personnalisation peut aboutir à un système d’exploitation non fonctionnel.
GenImage ne générera pas de modèle de solution Visual Studio.
Procédure générale
Le processus global pour créer une image Validation OS est le suivant :
Montez le fichier ISO de Validation OS à un emplacement spécifique sur le système de fichiers du PC technicien.
Démarrez une invite de commande avec élévation de privilèges et naviguez jusqu’au dossier
<ISO_ROOT>:\cabs
.[Facultatif] ajoutez les pilotes à l’image Validation OS.
[Facultatif] créez un fichier de configuration de fonctionnalités personnalisé.
[Facultatif] ajoutez les fonctionnalités ou packages à la demande souhaités à l’image Validation OS.
[Facultatif] définissez/remplacez les clés de registre dans l’image Validation OS.
[Facultatif] incluez des binaires/applications personnalisés dans l’image Validation OS.
[Facultatif] définissez le fuseau horaire de l’image Validation OS.
Packages de fonctionnalités prédéfinies
L’ISO de Validation OS contient des définitions de packages de fonctionnalités prédéfinis dans le dossier <ISO_ROOT>:\GenImage\configs
. Ces fichiers .pkg
peuvent être ouverts dans un éditeur de texte pour examiner leur contenu. La section supérieure de ces fichiers contient plus d’informations sur la fonctionnalité spécifique.
Créer un package de fonctionnalités personnalisé
Si les définitions de packages de fonctionnalités prédéfinies fournies sur l’ISO de Validation OS ne sont pas appropriées pour un scénario donné, un package de fonctionnalités personnalisé peut être facilement défini en suivant le même format convivial que les fichiers .pkg
prédéfinis :
Tout ce qui suit un
#
est considéré comme un commentaire.Une ligne par nom de package (.cab) sans l’extension de fichier. Ces cabs se trouvent sous
<ISO_ROOT>:\cabs\neutral
et avec des packages linguistiques correspondants sous<ISO_ROOT>:\cabs\en-us
(si approprié).Une référence à une autre définition de fonctionnalité à inclure en utilisant le format +include
<package_name>.<ext>
.
Les packages inclus peuvent se trouver soit dans le même répertoire que le fichier de définition de package personnalisé, soit ils peuvent être l’un des fichiers .pkg
fournis dans le cadre de l’ISO Validation OS sous <ISO_ROOT>:\GenImage\configs
.
Remarque
Il n’est pas nécessaire de spécifier un chemin de fichier pour les packages inclus.
- La version wow64 du package ne doit pas être ajoutée au fichier de configuration. GenImage inclura automatiquement la version wow du package si elle existe.
Remarque
Si un package (.cab) est listé plusieurs fois soit par une entrée en double dans le fichier, soit par une définition de fonctionnalité incluse, GenImage appliquera ce package une seule fois.
Important
Certaines fonctionnalités ont des dépendances inter-packages (cab-à-cab), ce qui signifie que l’image Validation OS générée ne fonctionnera pas à moins que tous les packages requis soient inclus. Ces dépendances ne peuvent pas être imposées par GenImage, il est donc possible de générer une image Validation OS non fonctionnelle ou partiellement fonctionnelle en utilisant des définitions de fonctionnalités personnalisées.
Spécification de l’image de base (-ImagePath
et -ImageFile
)
Le paramètre de ligne de commande -ImageFile:
peut être utilisé pour fournir le nom de l’image de base Validation OS.
Lors de l’utilisation du fichier ISO Validation OS fourni, ce paramètre peut être ignoré car GenImage par défaut utilisera ValidationOS.wim
.
Le paramètre de ligne de commande -ImagePath:
peut être utilisé pour fournir le chemin vers l’image de base Validation OS.
Lors de l’utilisation du fichier ISO Validation OS fourni, ce paramètre peut être ignoré car GenImage par défaut utilisera la racine du montage de l’ISO.
Inclusion de fonctionnalités (-PackagesList:
)
L’argument de ligne de commande -PackagesList : permet l’utilisation d’une ou plusieurs fonctionnalités prédéfinies ou personnalisées en fournissant le chemin vers le fichier de configuration.
Lors de la spécification de plusieurs fichiers .pkg
, utilisez soit ce paramètre plusieurs fois :
-PackagesList:<file1> -PackagesList:<file2> [...]
ou utilisez la syntaxe suivante :
-PackagesList:"<file1>,<file2>[,...]"
Lors de l’utilisation de ce format, assurez-vous que la liste séparée par des virgules est entourée de guillemets doubles.
-PackageList
et -PkgLst: sont des alias pour -PackagesList:
GenImage recherchera le package à la demande sous <ISO_ROOT>:\cabs\neutral
et <ISO_ROOT>:\cabs\en-us
, sauf s’il est remplacé par le paramètre de ligne de commande -PackagePath:.
Inclusion de packages à la demande sans utiliser de définitions de fonctionnalités (-Packages:
)
Le paramètre de ligne de commande -Packages:
peut être utilisé pour fournir une liste séparée par des virgules des noms de packages à la demande à inclure dans l’image Validation OS personnalisée. La liste doit être entourée de guillemets doubles.
L’ajout des variantes wow64 des packages sera toujours pris en charge par GenImage, il n’est pas nécessaire de les spécifier en utilisant le paramètre -Packages:
.
En raison de la longueur des noms de packages, il est facile de créer une ligne de commande très longue en utilisant le paramètre -Packages:
, il est donc conseillé de créer une définition de fonctionnalité personnalisée pour ajouter plusieurs packages. Pour plus de détails sur les définitions de fonctionnalités personnalisées, voir Créer un package de fonctionnalités personnalisé.
Remplacement de l’emplacement de package par défaut (-PackagePath
)
Le paramètre de ligne de commande -PackagePath:
peut être utilisé pour fournir le chemin vers les packages Validation OS à la demande. Sous le chemin fourni, des répertoires neutre et en-us doivent exister contenant les fichiers de package à la demande respectifs (y compris les versions wow si approprié).
Lors de l’exécution de GenImage à partir de l’ISO Validation OS, ce paramètre peut être ignoré, car GenImage par défaut utilisera <ISO_ROOT>:\cabs
.
Ajout de pilotes .inf à votre image Validation OS (-Drivers:
/ -DriversOnly
)
Le paramètre de ligne de commande -Drivers: peut être utilisé pour fournir le chemin vers un référentiel spécifique de pilotes. GenImage ajoutera de manière récursive tous les pilotes sous le chemin spécifié.
Si les pilotes sont structurés sous <WinVOS_Root>\Drivers\<my_device>,
, le paramètre de ligne de commande -HW:<my_device>
peut être utilisé comme raccourci pour inclure ces pilotes. Veuillez consulter la section « Spécification du chemin de l’image Validation OS personnalisée » pour plus de détails sur WinVOS_Root.
Lorsque les pilotes sont inclus dans l’image Validation OS personnalisée, GenImage ajoutera automatiquement le package de fonctionnalités <ISO_ROOT>\GenImage\configs\usb.pkg
pour garantir que les pilotes disposent des pilotes de classe de base les plus simples. Cependant, l’utilisation du commutateur de ligne de commande -SkipDeviceFeatures
annulera ce comportement.
L’utilisation du commutateur de ligne de commande -DriversOnly permet d’ajouter des pilotes sans inclure de fonctionnalités ou de packages individuels.
Sélection de la cible de démarrage de l’image Validation OS (-x
)
L’image WIM Validation OS personnalisée peut être générée pour cibler deux scénarios d’utilisation différents : appliquer l’image directement sur le disque dur interne d’un appareil cible (démarrer depuis C :) ou utiliser le fichier .wim généré pour remplacer boot.wim sur une clé USB WinPE (démarrer depuis X :).
Pour accommoder les deux scénarios, le ValidationOS.wim de base expédié à la racine de l’ISO contient deux partitions : la partition 1 est utilisée pour être compatible avec la récupération sur C :, et la partition 2 pour prendre en charge les scénarios USB (démarrer depuis X :).
Par défaut, GenImage produira ValidationOS.wim pour être récupéré sur le disque dur interne d’un ordinateur cible (démarrer depuis C :).
Le paramètre de ligne de commande -x
peut être utilisé pour générer une image prenant en charge le scénario de démarrage sur clé USB depuis X :.
Remarque : -usb
est un alias du paramètre -x
.
Inclusion de fichiers personnalisés dans l’image (-AddedSW
et -AddedSWTargetDir
)
Tous les fichiers sous le chemin spécifié pour le paramètre de ligne de commande -AddedSW:
seront copiés dans l’image Validation OS personnalisée. Par défaut, le contenu de ce chemin sera copié sous <WIM_ROOT>:\Programs\<folder>
, où folder est le nom du dossier à inclure. Par exemple, -AddedSW:D:\Test\MyFiles
sera copié dans <WIM_ROOT>:\Programs\MyFiles
.
-AddedSW
peut être spécifié plusieurs fois en pointant vers différents emplacements.
Le paramètre de ligne de commande -AddedSWTargetDir:
peut être utilisé pour remplacer l’emplacement cible dans l’image Validation OS personnalisée.
Le commutateur de ligne de commande -NoPackages
peut être utilisé pour post-traiter une image Validation OS déjà personnalisée et ajouter des fichiers en tant qu’étape séparée.
Modification du registre (-RegistryImport:
)
Le paramètre de ligne de commande -RegistryImport:
peut être utilisé pour appliquer un fichier standard Windows Registry Editor Version 5.00 .reg
à l’image Validation OS personnalisée.
Le commutateur de ligne de commande -NoPackages
peut être utilisé pour post-traiter une image Validation OS déjà personnalisée et personnaliser le registre en tant qu’étape séparée.
Changement de fuseau horaire (-TimeZone:
)
Le paramètre de ligne de commande -TimeZone:
peut être utilisé pour modifier le fuseau horaire de l’image Validation OS personnalisée. La chaîne fournie doit être un fuseau horaire Windows valide, sinon GenImage échouera.
Spécification du chemin de l’image Validation OS personnalisée (-OutPath:
/ -WinVOS_Root:
)
Lors de l’exécution de GenImage à partir de l’ISO Validation OS monté, il par défaut produira sa sortie (et tout le contenu intermédiaire) dans le répertoire C:\WinVOS\out\<date>-<time>
(par exemple C:\WinVOS\out\240116-1242
). Ce comportement peut être modifié, mais à l’aide des paramètres de -OutPath:
ligne de commande ou de ligne -WinVOS_Root:
de commande. La différence entre ces deux paramètres est la suivante :
-OutPath:
spécifie l’emplacement de sortie exact, donc le Validation OS WIM personnalisé et tout le contenu intermédiaire seront créés sous ce répertoire.
Important
Utiliser le même -OutPath:
pour une exécution ultérieure de GenImage peut entraîner des effets secondaires inattendus.
-WinVOS_Root:
créera un sous-dossier out\<date>-<time>
sous le répertoire spécifié.
Conseil
L’utilisation de -WinVOS_Root:
est préférée à l’utilisation de -OutPath:
pour éviter les problèmes de conflit de fichiers temporaires ou de fichiers .wim laissés montés.
Par défaut, GenImage utilisera -OutPath:
pour monter le WIM pour traitement. Le paramètre de ligne de commande -MountDir:
peut être utilisé pour remplacer l’emplacement de ce point de montage intermédiaire.
Nettoyage des WIM montés potentiellement bloqués (-CleanUp
)
Si GenImage est interrompu ou qu’un WIM monté est bloqué, le paramètre de ligne de commande -CleanUp
peut être utilisé pour tenter un nettoyage automatique.
Ce paramètre ne peut être utilisé seul.
Ignorer la confirmation du traitement de l’image (-NoWait
)
Le paramètre de ligne de commande -NoWait
peut être utilisé pour ignorer la confirmation après l’affichage de l’option de génération d’image et poursuivre le traitement de l’image.
Sortie détaillée.
Le paramètre de ligne de commande -v
peut être utilisé pour changer le niveau de journalisation de GenImage en mode détaillé.
L’utilisation de ce commutateur générera beaucoup de sorties, et il est recommandé de rediriger la sortie standard vers un fichier.
Afficher l’utilisation du script
Le paramètre de ligne de commande -h
peut être utilisé pour afficher les informations d’utilisation du script.
-?
et -help
sont des alias pour -h
Exemples de GenImage
En supposant que l’ISO Validation OS est monté sur J:
, voici quelques exemples de génération de WIM Validation OS personnalisés :
Ajoutez la fonctionnalité multimédia sans pilotes en utilisant les valeurs par défaut de l’ISO.
J:\GenImage>GenImage.cmd -PackagesList:J:\GenImage\configs\multimedia.pkg
Ajoutez les fonctionnalités multimédia et Wi-Fi avec des pilotes en utilisant les valeurs par défaut de l’ISO, en sautant la confirmation.
En supposant que les pilotes sont placés sous D:\Drivers\MyDevice
:
J:\GenImage>GenImage.cmd -PackagesList:J:\GenImage\configs\multimedia.pkg -PackagesList:J:\GenImage\configs\wifi.pkg -drivers:D:\Drivers\MyDevice -NoWait
... ou ...
J:\GenImage>GenImage.cmd -PackagesList:"J:\GenImage\configs\multimedia.pkg,J:\GenImage\configs\wifi.pkg" -drivers:D:\Drivers\MyDevice -NoWait
Ajoutez la fonctionnalité d’approvisionnement sans pilotes en utilisant un WIM précédemment personnalisé.
J:\GenImage>GenImage.cmd -PackagesList:J:\GenImage\configs\provisioning.pkg -ImagePath:C:\WinVOS\out\240116-1530
Ajoutez la fonctionnalité de débogage avec des pilotes et incluez Python.
En supposant que Python est extrait sous D:\Staging\Python
et que les pilotes sont placés sous D:\Drivers\MyDevice
.
J:\GenImage>GenImage.cmd -PackagesList:J:\GenImage\configs\debug.pkg -ImagePath:J:\ -Drivers:D:\Drivers\MyDevice -AddedSW:D:\Staging\Python
Utilisation complète de GenImage.cmd
GenImage.cmd est hautement personnalisable pour prendre en charge plusieurs scénarios personnalisés. Voici la liste complète des paramètres qu’il accepte, ainsi que quelques exemples d’utilisation :
[-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"
Remarque sur l’utilisation de la version correspondante de l’ensemble d’outils dism pour la création d’images
Lors de l’exécution de GenImage.cmd à partir de l’ISO monté, le script préfèrera utiliser le dism.exe fourni sur l’ISO avec GenImage.cmd. C’est la version recommandée de dism pour toute tâche de manipulation d’image car elle correspond à la version de l’outil utilisée pour créer le ValidationOS.wim expédié et les packages optionnels.
(Expérimental) Ajouter la prise en charge de WWAN
Attention
Ceci est une fonctionnalité expérimentale avec un support très limité.
Validation OS a introduit un support préliminaire pour WWAN, afin de fournir une interaction avec le modem via des commandes AT.
Deux packages doivent être ajoutés à la composition de l’image : Microsoft-WinVOS-WWAN-Package
et Microsoft-WinVOS-PnP-Settings
.
Ce scénario n’est pas pris en charge par GenImage, ce qui signifie que les packages doivent être appliqués en utilisant dism.exe fourni sur l’ISO Validation OS. Assurez-vous d’utiliser dism.exe depuis <ISO_ROOT>:\GenImage\Tools\DISM\%PROCESSOR_ARCHITECTURE%
où PROCESSOR_ARCHITECTURE
est l’architecture du processeur de l’ordinateur technicien (par exemple AMD64).