powershell-scripts/README.md

powershell-scripts

A collection of standalone PowerShell scripts for Windows setup and deployment tasks. All scripts must be run from an elevated (Administrator) PowerShell prompt.

Contents

• Install-WSL2Ubuntu.ps1 — Enable WSL 2 and install Ubuntu.
• New-Win11GeneralizedImage.ps1 — Generalize a Windows 11 Pro reference machine and capture it to a deployment WIM.
• New-WinPEUsbMedia.ps1 — Build a bootable WinPE USB drive for use with the capture script.

---

Install-WSL2Ubuntu.ps1

Enables the Windows features required for WSL 2 and installs the latest Ubuntu distribution.

What it does:

1. Enables the Microsoft-Windows-Subsystem-Linux and VirtualMachinePlatform optional features.
2. Sets WSL 2 as the default WSL version.
3. Installs/updates the WSL kernel components.
4. Installs the latest Ubuntu distribution via wsl --install -d Ubuntu.
5. If a restart is required after enabling the features, prompts to reboot and automatically resumes the script after sign-in (via a scheduled task).

Parameters:

Parameter	Default	Description
-Distribution	Ubuntu	The WSL distribution name to install.

Usage:

powershell -ExecutionPolicy Bypass -File .\Install-WSL2Ubuntu.ps1

---

New-Win11GeneralizedImage.ps1

Prepares a Windows 11 Pro reference machine and creates a generalized (sysprepped) WIM image for deployment. Operates in two modes.

Mode: Sysprep (default)

Run on the reference machine while it's still the running OS.

1. Optionally removes provisioned AppX packages matching supplied wildcard patterns.
2. Runs DISM /Online /Cleanup-Image /StartComponentCleanup /ResetBase to shrink the component store.
3. Generates a minimal unattend.xml (skips OOBE prompts) if one isn't supplied.
4. Runs sysprep.exe /oobe /generalize /shutdown /unattend:<file>. The machine powers off automatically once done.

Windows cannot capture its own running volume — after sysprep shuts the machine down, boot it from WinPE media (see New-WinPEUsbMedia.ps1) to actually capture the image.

Parameters:

Parameter	Default	Description
-Mode	Sysprep	Sysprep or Capture.
-UnattendPath	(generated)	Path to a custom unattend.xml.
-RemoveProvisionedApps	@()	Wildcard patterns of AppX packages to remove, e.g. "*Xbox*","*Solitaire*".

Usage:

.\New-Win11GeneralizedImage.ps1 -Mode Sysprep -RemoveProvisionedApps "*Xbox*","*Solitaire*"

Mode: Capture

Run from WinPE, after the reference machine has shut down from sysprep, with the generalized Windows volume mounted as an offline drive letter (not the running OS).

Captures the offline volume into a .wim file using DISM /Capture-Image. Refuses to run against the currently running OS volume as a safety check.

Parameters:

Parameter	Default	Description
-SourceDrive	(required)	Drive letter of the generalized volume, e.g. D:.
-DestinationWim	(required)	Output path for the .wim file, e.g. E:\Images\Win11Pro.wim.
-ImageName	Windows 11 Pro - Deployment	Friendly name stored in the WIM metadata.
-Compress	max	DISM compression level: fast, max, or none.

Usage:

.\New-Win11GeneralizedImage.ps1 -Mode Capture -SourceDrive D: -DestinationWim "E:\Images\Win11Pro.wim"

---

New-WinPEUsbMedia.ps1

Builds a bootable WinPE USB drive that can be used to run New-Win11GeneralizedImage.ps1 -Mode Capture.

Prerequisites: the Windows ADK and the "Windows PE add-on for the ADK" must be installed. Both can be installed via winget:

winget install --id Microsoft.WindowsADK
winget install --id Microsoft.WindowsADK.WinPEAddon

What it does:

1. Locates copype.cmd / MakeWinPEMedia.cmd from the installed ADK and loads the Deployment Tools environment.
2. Runs copype to stage a WinPE working folder for the chosen architecture.
3. Copies New-Win11GeneralizedImage.ps1 onto the WinPE media so it's available after boot.
4. Prompts for confirmation, then formats the target USB drive and copies the bootable WinPE media onto it via MakeWinPEMedia /UFD.

⚠️ The target USB drive is completely erased. Double-check -UsbDriveLetter before confirming.

Parameters:

Parameter	Default	Description
-UsbDriveLetter	(required)	Drive letter of the USB flash drive to format, e.g. F:.
-Architecture	amd64	WinPE architecture: amd64, x86, or arm64.
-WorkingDirectory	C:\WinPE_<Architecture>	Folder used to stage the WinPE image files.
-IncludeCaptureScript	New-Win11GeneralizedImage.ps1 next to this script	Extra script copied onto the WinPE media.

Usage:

.\New-WinPEUsbMedia.ps1 -UsbDriveLetter F: -Architecture amd64

---

Typical end-to-end workflow

1. New-WinPEUsbMedia.ps1 — build the WinPE capture USB (one-time, on any machine with the ADK installed).
2. New-Win11GeneralizedImage.ps1 -Mode Sysprep — generalize the reference machine; it shuts down automatically.
3. Boot the reference machine from the WinPE USB.
4. New-Win11GeneralizedImage.ps1 -Mode Capture — capture the generalized volume to a .wim file for deployment.