Anpassen Ihres Validation OS-Image mit GenImage (Advanced)
GenImage bietet eine flexible und hochgradig anpassbare Befehlszeilenschnittstelle, um Validation OS-Images genau für Ihre Szenarien zu erstellen. Der Validation OS Image Builder verwendet GenImage, erstellt jedoch eine Abstraktionsebene für einen praktischen, aber etwas eingeschränkten UI-basierten Workflow. GenImage kann viel mehr als das, was auf der Benutzeroberfläche von Validation OS Image Builder angezeigt wird. In diesem Abschnitt werden die Nuancen der Generierung eines vollständig anpassbaren Validation OS-Image detailliert beschrieben.
Hinweis
Vollständig benutzerdefinierte Images bedeuten, dass das mit einer beliebigen Liste von Anpassungspaketen erstellte Validation OS-Image möglicherweise zu einem nicht funktionsfähigen Betriebssystem führt.
GenImage generiert keine Visual Studio-Projektmappenvorlage.
Übersicht über den Prozess
Der allgemeine Prozess zum Erstellen eines Validation OS-Image ist wie folgt:
Stellen Sie die ISO-Datei von Validation OS in einem bestimmten Speicherort im Dateisystem des Techniker-PCs bereit.
Starten Sie eine Eingabeaufforderung mit erhöhten Rechten, und navigieren Sie zum
<ISO_ROOT>:\cabs-Ordner.[Optional] Fügen Sie die Treiber zum Validation OS-Image hinzu.
[Optional] Erstellen Sie eine benutzerdefinierte Featurekonfigurationsdatei.
[Optional] Fügen Sie dem Validation OS-Image die gewünschten On-Demand-Features oder -Pakete hinzu.
[Optional] Legen Sie den Registrierungsschlüssel im Validation OS-Image fest bzw. setzen Sie ihn außer Kraft.
[Optional] Schließen Sie benutzerdefinierte Binärdateien/Anwendungen in das Validation OS-Image ein.
[Optional] Legen Sie die Zeitzone des Validation OS-Images fest.
Vordefinierte Featurepakete
Die ISO-Datei von Validation OS enthält vordefinierte Featurepaketdefinitionen im <ISO_ROOT>:\GenImage\configs-Ordner. Diese .pkg-Dateien können in einem Text-Editor geöffnet werden, um deren Inhalt zu untersuchen. Der obere Abschnitt dieser Dateien enthält weitere Informationen zu dem jeweiligen Feature.
Erstellen eines benutzerdefinierten Featurepakets
Wenn die vordefinierten Featurepaketdefinitionen im Validation OS ISO für ein bestimmtes Szenario nicht geeignet sind, kann ein benutzerdefiniertes Featurepaket problemlos im selben benutzerfreundlichen Format definiert werden, über das die vordefinierten .pkg-Dateien verfügen:
Alles, was nach einem
#kommt, wird als Kommentar betrachtet.Eine Zeile pro Paketname (.cab) ohne die Dateierweiterung. Diese Cabs befinden sich unter
<ISO_ROOT>:\cabs\neutralund mit übereinstimmenden Sprachpaketen unter<ISO_ROOT>:\cabs\en-us(falls zutreffend).Ein Verweis auf eine andere Featuredefinition, die mit dem +include
<package_name>.<ext>-Format eingeschlossen werden soll.
Enthaltene Pakete können sich entweder im selben Verzeichnis wie die benutzerdefinierte Paketdefinitionsdatei befinden, oder es kann sich um eine der .pkg-Dateien handeln, die im Rahmen der Validation OS-ISO unter <ISO_ROOT>:\GenImage\configs bereitgestellt werden.
Hinweis
Es ist nicht erforderlich, einen Dateipfad für enthaltene Pakete anzugeben.
- Die wow64-Version des Pakets sollte der Konfigurationsdatei nicht hinzugefügt werden. GenImage enthält automatisch die wow-Version des Pakets, falls vorhanden.
Hinweis
Wenn ein Paket (.cab) mehrmals entweder über doppelten Eintrag in der Datei oder über eine enthaltene Featuredefinition aufgeführt wird, wendet GenImage dieses Paket nur einmal an.
Wichtig
Einige Features weisen Abhängigkeiten zwischen Paketen (Cab-zu-Cab) auf. Dies bedeutet, dass das generierte Validation OS-Image nicht funktioniert, wenn nicht alle erforderlichen Pakete enthalten sind. Diese Abhängigkeiten können von GenImage nicht erzwungen werden. Daher ist es möglich, dass bei Verwendung benutzerdefinierter Featuredefinitionen ein nicht oder nur teilweise funktionsfähiges Validation OS-Image generiert wird.
Angeben des Basisimages (-ImagePath und -ImageFile)
Der -ImageFile:-Befehlszeilenparameter kann verwendet werden, um den Namen des Validation OS-Basis-Images anzugeben.
Wenn Sie mit der bereitgestellten ISO-Datei von Validation OS arbeiten, kann dieser Parameter übersprungen werden, da GenImage standardmäßig ValidationOS.wim verwendet.
Der -ImagePath:-Befehlszeilenparameter kann verwendet werden, um den Pfad zum Validation OS-Basis-Image anzugeben.
Wenn Sie mit der bereitgestellten ISO-Datei von Validation OS arbeiten, kann dieser Parameter übersprungen werden, da GenImage standardmäßig den Bereitstellungsstamm der ISO-Datei verwendet.
Einschließlich Features (-PackagesList:)
Das Befehlszeilenargument „-PackagesList:“ ermöglicht die Verwendung eines oder mehrerer vordefinierter oder benutzerdefinierter Features, indem der Pfad zur Konfigurationsdatei bereitgestellt wird.
Wenn Sie mehrere .pkg-Dateien angeben, verwenden Sie entweder diesen Parameter mehrmals:
-PackagesList:<file1> -PackagesList:<file2> [...]
oder verwenden Sie die folgende Syntax:
-PackagesList:"<file1>,<file2>[,...]"
Wenn Sie das letztere Format verwenden, stellen Sie sicher, dass die durch Kommas getrennte Liste in Anführungszeichen steht.
-PackageList und `-PkgLst: sind Aliase für -PackagesList:
GenImage sucht nach dem On-Demand-Paket unter <ISO_ROOT>:\cabs\neutral und <ISO_ROOT>:\cabs\en-us, es sei denn, es wird vom Befehlszeilenparameter „-PackagePath:“ außer Kraft gesetzt.
Einschließen von On-Demand-Paketen ohne Verwendung von Featuredefinitionen (-Packages:)
Der -Packages:-Befehlszeilenparameter kann verwendet werden, um eine durch Kommas getrennte Liste von On-Demand-Paketnamen bereitzustellen, die im angepassten Validation OS-Image enthalten sein sollen. Die Liste muss in doppelte Anführungszeichen gesetzt werden.
Das Hinzufügen der wow64-Varianten der Pakete wird von GenImage weiterhin behandelt. Es ist nicht erforderlich, sie mit dem -Packages:-Parameter anzugeben.
Aufgrund der Länge der Paketnamen ist es einfach, eine sehr lange Befehlszeile mit dem -Packages:-Parameter zu erstellen. Daher wird empfohlen, eine benutzerdefinierte Featuredefinition zum Hinzufügen mehrerer Pakete zu erstellen. Ausführliche Informationen zu benutzerdefinierten Featuredefinitionen finden Sie unter „Erstellen eines benutzerdefinierten Featurepakets“.
Überschreiben des Standardpaketspeicherorts (-PackagePath)
Der -PackagePath:-Befehlszeilenparameter kann verwendet werden, um den Pfad zu den On-Demand-Validation OS-Paketen bereitzustellen. Unter dem angegebenen Pfad müssen ein neutrales und ein en-us-Verzeichnis vorhanden sein, die die jeweiligen On-Demand-Paketdateien (ggf. einschließlich wow-Versionen) enthalten.
Bei der Ausführung von GenImage über die ISO-Datei von Validation OS kann dieser Parameter übersprungen werden, da GenImage standardmäßig <ISO_ROOT>:\cabs verwendet.
Hinzufügen von .inf-Treibern zu Ihrem Validation OS-Image (-Drivers: / -DriversOnly)
Der Befehlszeilenparameter „-Drivers:“ kann verwendet werden, um den Pfad zu einem gerätespezifischen Repository von Treibern bereitzustellen. GenImage fügt rekursiv alle Treiber unter dem angegebenen Pfad hinzu.
Wenn die Treiber unter <WinVOS_Root>\Drivers\<my_device>, strukturiert sind, kann der -HW:<my_device>-Befehlszeilenparameter als Verknüpfung verwendet werden, um diese Treiber einzuschließen. Weitere Informationen zu „WinVOS_Root“ finden Sie unter „Angeben des Pfads des angepassten Validation OS-Images“.
Wenn Treiber im angepassten Validation OS-Image enthalten sind, fügt GenImage automatisch das <ISO_ROOT>\GenImage\configs\usb.pkg-Featurepaket hinzu, um sicherzustellen, dass Treiber über die einfachsten Klassentreiber verfügen, damit sie funktionieren. Die Verwendung des -SkipDeviceFeatures-Befehlszeilenschalters setzt dieses Verhalten jedoch außer Kraft.
Die Verwendung des Befehlszeilenschalters „-DriversOnly“ ermöglicht das Hinzufügen von Treibern ohne Einschließen von Features oder einzelnen Paketen.
Auswählen des Startziels für das Validation OS-Image (-x)
Das angepasste Validation OS WIM-Image kann für zwei verschiedene Verwendungsszenarien generiert werden: Wenden Sie das Image direkt auf der internen Festplatte eines Zielgeräts an (Booten von C:), oder verwenden Sie die generierte WIM-Datei, um boot.wim auf einem WinPE-USB-Laufwerk zu ersetzen (Booten von X:).
Um beide Szenarien zu berücksichtigen, enthält die im Stammverzeichnis des ISO enthaltene Basisdatei „ValidationOS.wim“ zwei Partitionen: Partition 1 wird für die Kompatibilität mit der Wiederherstellung nach C: verwendet und Partition 2 zur Unterstützung der USB-Szenarien (Booten von X:).
Standardmäßig erzeugt GenImage ValidationOS.wim, um auf der internen Festplatte eines Zielcomputers wiederhergestellt zu werden (Booten von C:).
Der -x-Befehlszeilenparameter kann verwendet werden, um ein Image zu generieren, das das Booten des USB-Laufwerks vom X:-Szenario unterstützt.
Hinweis: -usb ist ein Alias für den -x-Parameter.
Einschließen von benutzerdefinierten Dateien in das Image (-AddedSW und -AddedSWTargetDir)
Alle Dateien unter dem Pfad, der für den -AddedSW:-Befehlszeilenparameter angegeben ist, werden in das angepasste Validation OS-Image kopiert. Standardmäßig wird der Inhalt dieses Pfads unter <WIM_ROOT>:\Programs\<folder> kopiert, wobei „Ordner“ der Name des einzubindenden Ordners ist. Beispielsweise wird -AddedSW:D:\Test\MyFiles in <WIM_ROOT>:\Programs\MyFiles kopiert.
-AddedSW kann mehrmals angegeben werden und auf verschiedene Speicherorte verweisen.
Der -AddedSWTargetDir:-Befehlszeilenparameter kann verwendet werden, um den Zielspeicherort mit dem angepassten Validation OS-Image außer Kraft zu setzen.
Der -NoPackages-Befehlszeilenschalter kann verwendet werden, um ein bereits angepasstes Validation OS-Image nachzubearbeiten und Dateien als separaten Schritt hinzuzufügen.
Ändern der Registrierung (-RegistryImport:)
Der -RegistryImport:-Befehlszeilenparameter kann verwendet werden, um einen standardmäßigen Windows-Registrierungs-Editor Version 5.00 .reg-Datei auf das angepasste Validation OS-Image anzuwenden.
Der -NoPackages-Befehlszeilenschalter kann verwendet werden, um ein bereits angepasstes Validation OS-Image nachzubearbeiten und die Registrierung als separaten Schritt anzupassen.
Ändern der Zeitzone (-TimeZone:)
Der -TimeZone:-Befehlszeilenparameter kann verwendet werden, um die Zeitzone des angepassten Validation OS-Images zu ändern. Die angegebene Zeichenfolge muss eine gültige Windows-Zeitzone sein, andernfalls schlägt GenImage fehl.
Angeben des Pfads des angepassten Validation OS-Images (-OutPath: / -WinVOS_Root:)
Beim Ausführen von GenImage aus der bereitgestellten Validation OS ISO wird standardmäßig die Ausgabe (und alle Zwischeninhalte) im das C:\WinVOS\out\<date>-<time>-Verzeichnis (z. B. C:\WinVOS\out\240116-1242) generiert. Dieses Verhalten kann geändert werden, indem entweder die -OutPath:-Befehlszeilenparameter oder die -WinVOS_Root:-Befehlszeilenparameter verwendet werden. Der Unterschied zwischen diesen beiden ist wie folgt:
-OutPath: gibt den genauen Ausgabespeicherort an, sodass das angepasste Validation OS WIM und alle Zwischeninhalte unter diesem Verzeichnis erstellt werden.
Wichtig
Die Verwendung desselben -OutPath: für eine nachfolgende Ausführung von GenImage kann zu unerwarteten Nebenwirkungen führen.
-WinVOS_Root: erstellt einen out\<date>-<time>-Unterordner unter dem angegebenen Verzeichnis.
Tipp
Die Verwendung von -WinVOS_Root: wird -OutPath: vorgezogen, um Probleme mit Konflikten zwischen temporären Dateien oder bereitgestellten .wim-Dateien zu vermeiden.
Standardmäßig verwendet GenImage -OutPath: zum Bereitstellen des WIM zur Verarbeitung. Der -MountDir:-Befehlszeilenparameter kann verwendet werden, um den Speicherort dieses zwischengeschalteten Bereitstellungspunkts außer Kraft zu setzen.
Bereinigen potenziell hängender WIMs (-CleanUp)
Wenn GenImage unterbrochen wird oder eine bereitgestellte WIM hängen bleibt, kann der -CleanUp-Befehlszeilenparameter verwendet werden, um eine automatische Bereinigung durchzuführen.
Dieser Parameter kann nur allein verwendet werden.
Bestätigung der Image-Verarbeitung überspringen (-NoWait)
Der -NoWait-Befehlszeilenparameter kann verwendet werden, um die Bestätigung nach dem Anzeigen der Image-Generierungsoption zu überspringen und mit der Image-Verarbeitung fortzufahren.
Ausführliche Ausgabe
Der -v-Befehlszeilenparameter kann verwendet werden, um die Protokollierungsebene von GenImage in „ausführlich“ zu ändern.
Die Verwendung dieses Schalters erzeugt eine große Ausgabemenge und es wird empfohlen, die Standardausgabe in eine Datei umzuleiten.
Skriptverwendung anzeigen
Der -h-Befehlszeilenparameter kann zum Anzeigen von Skriptverwendungsinformationen verwendet werden.
-? und -help sind Aliasse für -h
GenImage-Beispiele
Vorausgesetzt, das Validation OS ISO ist auf J: bereitgestellt, finden Sie hier einige Beispiele für die Generierung angepasster Validation OS WIMs.
Hinzufügen von Multimediafeatures ohne Treiber mit ISO-Standardwerten
J:\GenImage>GenImage.cmd -PackagesList:J:\GenImage\configs\multimedia.pkg
Hinzufügen von Multimedia- und WLAN-Features mit Treibern mit ISO-Standardwerten, Überspringen der Bestätigung
Vorausgesetzt, die Treiber werden unter D:\Drivers\MyDevice platziert
J:\GenImage>GenImage.cmd -PackagesList:J:\GenImage\configs\multimedia.pkg -PackagesList:J:\GenImage\configs\wifi.pkg -drivers:D:\Drivers\MyDevice -NoWait
... oder ...
J:\GenImage>GenImage.cmd -PackagesList:"J:\GenImage\configs\multimedia.pkg,J:\GenImage\configs\wifi.pkg" -drivers:D:\Drivers\MyDevice -NoWait
Hinzufügen des Bereitstellungsfeatures ohne Treiber mit zuvor angepasster WIM
J:\GenImage>GenImage.cmd -PackagesList:J:\GenImage\configs\provisioning.pkg -ImagePath:C:\WinVOS\out\240116-1530
Hinzufügen von Debugfeatures mit Treibern und Einschließen von Python
Vorausgesetzt, Python wird unter D:\Staging\Python extrahiert und Treiber werden unter D:\Drivers\MyDevice platziert
J:\GenImage>GenImage.cmd -PackagesList:J:\GenImage\configs\debug.pkg -ImagePath:J:\ -Drivers:D:\Drivers\MyDevice -AddedSW:D:\Staging\Python
Vollständige Nutzung von GenImage.cmd
GenImage.cmd ist hochgradig anpassbar, um mehrere benutzerdefinierte Szenarien zu unterstützen. Hier ist die vollständige Liste der erforderlichen Parameter sowie einige Anwendungsbeispiele:
[-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"
Hinweis zur Verwendung der passenden Version des Dism-Toolsets für die Image-Erstellung
Beim Ausführen von GenImage.cmd aus der bereitgestellten ISO verwendet das Skript vorzugsweise die Datei dism.exe, die zusammen mit GenImage.cmd auf dem ISO mitgeliefert wird. Dies ist die empfohlene Version von dism für alle Image-Bearbeitungsaufgaben, da sie mit der Toolversion übereinstimmt, die zum Erstellen der mitgelieferten Datei „ValidationOS.wim“ und der optionalen Pakete verwendet wurde.
(Experimentell) Hinzufügen der WWAN-Unterstützung
Achtung
Dies ist ein experimentelles Feature mit sehr eingeschränkter Unterstützung.
Validation OS hat frühzeitig Unterstützung für WWAN eingeführt, um die Interaktion mit dem Modem über AT-Befehle zu ermöglichen.
Der Image-Komposition müssen zwei Pakete hinzugefügt werden: Microsoft-WinVOS-WWAN-Package und Microsoft-WinVOS-PnP-Settings.
Dieses Szenario wird von GenImage nicht unterstützt. Dies bedeutet, dass die Pakete mithilfe von dism.exe angewendet werden müssen, das auf der Validation OS ISO bereitgestellt wird. Stellen Sie sicher, dass Sie dism.exe aus <ISO_ROOT>:\GenImage\Tools\DISM\%PROCESSOR_ARCHITECTURE% verwenden, wobei PROCESSOR_ARCHITECTURE die Prozessorarchitektur des Technikercomputers (z. B. AMD64) ist.