# 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](#install-wsl2ubuntups1) — Enable WSL 2 and install Ubuntu.
- [New-Win11GeneralizedImage.ps1](#new-win11generalizedimageps1) — Generalize a Windows 11 Pro reference machine and capture it to a deployment WIM.
- [New-WinPEUsbMedia.ps1](#new-winpeusbmediaps1) — 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
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](#new-winpeusbmediaps1)) 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:**
```powershell
.\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:**
```powershell
.\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](https://learn.microsoft.com/windows-hardware/get-started/adk-install) and the "Windows PE add-on for the ADK" must be installed. Both can be installed via winget:
```powershell
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:**
```powershell
.\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.