mirror of
https://github.com/rbalsleyMSFT/FFU.git
synced 2026-06-13 18:07:20 -06:00
Add flexible device naming options to Unattend delivery
Introduces new parameters and UI controls to give users more choice over device naming when applying an Unattend.xml file. Users can now specify a device name, use a static or template-based name with the `%serial%` variable, or continue using a list of prefixes. The UI is updated with a new Device Naming expander to guide the user through the options and clearly indicate the requirements for each mode, ensuring that mutually exclusive options like Copy Unattend and Inject Unattend are not selected together. Documentation is updated to reflect the new functionality.
This commit is contained in:
rbalsleyMSFT
+24
-8
@@ -199,24 +199,34 @@ This option is only available when **Build USB Drive** is checked.
|
||||
When enabled, the build process copies:
|
||||
|
||||
- **unattend_x64.xml** (for x64 builds) or **unattend_arm64.xml** (for arm64 builds) → renamed to **Unattend.xml** on the USB drive
|
||||
- **prefixes.txt** (if present) → copied alongside the unattend file
|
||||
- **prefixes.txt** → created from the **Device Naming** prefixes list when that mode is selected
|
||||
|
||||
During deployment, `ApplyFFU.ps1` detects the `Unattend` folder and uses these files to customize the device name and apply other Windows settings during OOBE.
|
||||
During deployment, `ApplyFFU.ps1` applies `Unattend.xml` whenever it is present. Device naming only happens when the **Device Naming** setting requires it, or when older media still uses the legacy prompt-based workflow.
|
||||
|
||||
#### Device Naming
|
||||
|
||||
Device naming can be done from PE. The way this works is by leveraging an unattend.xml file to either take input from the user at imaging time or read a list of prefix values and append the serial number of the device. There are some major benefits to doing this:
|
||||
Use the **Device Naming** expander to decide whether `ComputerName` should be set at deployment time. There are some major benefits to doing this:
|
||||
|
||||
1. Total deployment time is reduced if naming is set at FFU deployment time since there is no additional reboot done during OOBE.
|
||||
2. Reduces the need for multiple provisioning packages or autopilot profiles. This means you can use a single PPKG or autopilot profile.
|
||||
|
||||
#### Prompt for Device Name
|
||||
#### No Device Name
|
||||
|
||||
If you want to be prompted for the device name, simply check **Copy Unattend.xml.** This tells the build script to copy the appropriate architecture unattend_arch.xml file from the `C:\FFUDevelopment\Unattend` folder to the `.\unattend` folder on the deploy partition of the USB drive.
|
||||
This is the default option. The unattend file is still applied, but Windows generates a random computer name instead of forcing a prompt or a fixed name.
|
||||
|
||||
#### Device Naming with prefixes.txt
|
||||
#### Specify Device Name
|
||||
|
||||
If a `prefixes.txt` file exists in the `Unattend` folder and there are multiple prefixes in the file, the deployment script prompts the technician to select a prefix from the file. The prefix is combined with the device's serial number to create the computer name. If there is a single prefix, the technician is not prompted and the script will automatically select that prefix.
|
||||
Use this option when you want a static device name or a template such as `Comp-%serial%`.
|
||||
|
||||
- With **Copy Unattend.xml**, `%serial%` is resolved during deployment in PE.
|
||||
- With **Inject Unattend.xml**, only static names are supported.
|
||||
- **Copy Unattend.xml** and **Inject Unattend.xml** are mutually exclusive. Select only one.
|
||||
|
||||
#### Specify a list of Prefixes
|
||||
|
||||
This option writes `prefixes.txt` from the list in the UI. Enter one prefix per line or import an existing prefixes file. The source file can use any name because the UI now tracks the path separately.
|
||||
|
||||
If there is a single prefix, deployment uses it automatically. If there are multiple prefixes, the technician is prompted to select one. The selected prefix is combined with the device serial number to create the computer name.
|
||||
|
||||
For example, with a prefix of `CORP-` and a serial number of `ABC123`, the resulting computer name would be `CORP-ABC123` (truncated to 15 characters if necessary).
|
||||
|
||||
@@ -228,6 +238,10 @@ STORE-
|
||||
KIOSK-
|
||||
```
|
||||
|
||||
#### Legacy Prompt Behavior
|
||||
|
||||
Older deployment media that still has an unattend file with `ComputerName` set to the legacy placeholder value and no `prefixes.txt` file will still prompt for a device name during deployment.
|
||||
|
||||
{: .warning-title}
|
||||
|
||||
> Warning
|
||||
@@ -483,6 +497,8 @@ Controls the `-InjectUnattend` parameter. When checked, copies the architecture-
|
||||
|
||||
This option is only available when **Install Apps** is checked.
|
||||
|
||||
`Copy Unattend.xml` and `Inject Unattend.xml` are mutually exclusive. Select only one.
|
||||
|
||||
### How It Works
|
||||
|
||||
When enabled, the build process:
|
||||
@@ -522,7 +538,7 @@ This option is primarily intended for scenarios where:
|
||||
|
||||
| Limitation | Description |
|
||||
| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| **No prefixes.txt support** | Unlike the**Copy Unattend** option for USB drives, this method does not support `prefixes.txt` for dynamic device naming based on serial numbers |
|
||||
| **No prefixes.txt or %serial% support** | Unlike **Copy Unattend.xml**, this method does not support `prefixes.txt` or the `%serial%` variable for deployment-time device naming |
|
||||
| **Fixed configuration** | The unattend settings are baked into the FFU at build time and cannot be changed at deployment time |
|
||||
| **Requires VM to be built** | This option only works when**Install Apps** is `$true` because the unattend file is included in the Apps ISO |
|
||||
|
||||
|
||||
@@ -38,9 +38,13 @@ This table lists all top-level parameters in BuildFFUVM.ps1.
|
||||
| -CopyDrivers | bool | Copy Drivers to USB drive | When set to $true, will copy the drivers from the $FFUDevelopmentPath\Drivers folder to the Drivers folder on the deploy partition of the USB drive. Default is $false. |
|
||||
| -CopyPEDrivers | bool | Copy PE Drivers | When set to $true, enables adding WinPE drivers. By default copies drivers from $FFUDevelopmentPath\PEDrivers to the WinPE deployment media unless -UseDriversAsPEDrivers is also $true. |
|
||||
| -CopyPPKG | bool | Copy Provisioning Package | When set to $true, will copy the provisioning package from the $FFUDevelopmentPath\PPKG folder to the Deployment partition of the USB drive. Default is $false. |
|
||||
| -CopyUnattend | bool | Copy Unattend.xml | When set to $true, will copy the $FFUDevelopmentPath\Unattend folder to the Deployment partition of the USB drive. Default is $false. |
|
||||
| -CopyUnattend | bool | Copy Unattend.xml | When set to $true, will copy the $FFUDevelopmentPath\Unattend folder to the Deployment partition of the USB drive. Cannot be used together with -InjectUnattend. Default is $false. |
|
||||
| -CreateDeploymentMedia | bool | Create Deployment Media | When set to $true, this will create WinPE deployment media for use when deploying to a physical device. |
|
||||
| -CustomFFUNameTemplate | string | Custom FFU Name Template | Sets a custom FFU output name with placeholders. Allowed placeholders are: {WindowsRelease}, {WindowsVersion}, {SKU}, {BuildDate}, {yyyy}, {MM}, {dd}, {H}, {hh}, {mm}, {tt}. |
|
||||
| -DeviceNamingMode | string | Device Naming expander | Controls how device naming is handled when unattend content is copied to USB media or injected into the FFU. Accepted values are Legacy, None, Template, and Prefixes. The UI uses None, Template, and Prefixes. |
|
||||
| -DeviceNameTemplate | string | Specify Device Name | Sets the device name used when DeviceNamingMode is Template. Supports a static name or the %serial% token when -CopyUnattend is used. |
|
||||
| -DeviceNamePrefixesPath | string | Prefixes File Path | Path to the source prefixes file used for legacy copy or when -DeviceNamePrefixes is not supplied. Default is $FFUDevelopmentPath\Unattend\prefixes.txt. |
|
||||
| -DeviceNamePrefixes | string[] | Specify a list of Prefixes | Sets the prefixes used when DeviceNamingMode is Prefixes. Each entry becomes a line in prefixes.txt on the deployment media. |
|
||||
| -Disksize | uint64 | Disk Size (GB) | Size of the virtual hard disk for the virtual machine. Default is a 50GB dynamic disk. |
|
||||
| -DriversFolder | string | Drivers Folder | Path to the drivers folder. Default is $FFUDevelopmentPath\Drivers. |
|
||||
| -DriversJsonPath | string | Drivers.json Path | Path to a JSON file that specifies which drivers to download. |
|
||||
@@ -50,7 +54,7 @@ This table lists all top-level parameters in BuildFFUVM.ps1.
|
||||
| -FFUDevelopmentPath | string | FFU Development Path | Path to the FFU development folder. Default is $PSScriptRoot. |
|
||||
| -FFUPrefix | string | VM Name Prefix | Prefix for the generated FFU file. Default is _FFU. |
|
||||
| -Headers | hashtable | CLI only (no UI control) | Headers to use when downloading files. Not recommended to modify. |
|
||||
| -InjectUnattend | bool | Inject Unattend.xml | When set to $true and InstallApps is also $true, copies unattend_[arch].xml from $FFUDevelopmentPath\unattend to $FFUDevelopmentPath\Apps\Unattend\Unattend.xml so sysprep can use it inside the VM. Default is $false. |
|
||||
| -InjectUnattend | bool | Inject Unattend.xml | When set to $true and InstallApps is also $true, copies unattend_[arch].xml from $FFUDevelopmentPath\unattend to $FFUDevelopmentPath\Apps\Unattend\Unattend.xml so sysprep can use it inside the VM. Cannot be used together with -CopyUnattend. Default is $false. |
|
||||
| -InstallApps | bool | Install Applications | When set to $true, the script will create an Apps.iso file from the $FFUDevelopmentPath\Apps folder. It will also create a VM, mount the Apps.iso, install the apps, sysprep, and capture the VM. When set to $false, the FFU is created from a VHDX file, and no VM is created. |
|
||||
| -InstallDrivers | bool | Install Drivers to FFU | Install device drivers from the specified $FFUDevelopmentPath\Drivers folder if set to $true. Download the drivers and put them in the Drivers folder. The script will recurse the drivers folder and add the drivers to the FFU. |
|
||||
| -InstallOffice | bool | Install Office | Install Microsoft Office if set to $true. The script will download the latest ODT and Office files in the $FFUDevelopmentPath\Apps\Office folder and install Office in the FFU via VM. |
|
||||
|
||||
+13
-5
@@ -186,18 +186,26 @@ Another safety measure is **Select Specific USB Drives**. When you check **Selec
|
||||
|
||||
**Device Naming**
|
||||
|
||||
Device naming can be done from PE. The way this works is by leveraging an unattend.xml file to either take input from the user at imaging time or read a list of prefix values and append the serial number of the device. There are some major benefits to doing this:
|
||||
Use the **Device Naming** expander on the Build page to decide whether `ComputerName` should be set during deployment. There are some major benefits to doing this:
|
||||
|
||||
1. Total deployment time is reduced if naming is set at FFU deployment time since there is no additional reboot done during OOBE.
|
||||
2. Reduces the need for multiple provisioning packages or autopilot profiles. This means you can use a single PPKG or autopilot profile.
|
||||
|
||||
**Prompt for Device Name**
|
||||
**No Device Name**
|
||||
|
||||
If you want to be prompted for the device name, simply check **Copy Unattend.xml.** This tells the build script to copy the appropriate architecture unattend_arch.xml file from the `C:\FFUDevelopment\Unattend` folder to the `.\unattend` folder on the deploy partition of the USB drive.
|
||||
This is the default option. The unattend file is still applied, but Windows generates a random computer name.
|
||||
|
||||
**Specifying Multiple Name Prefixes**
|
||||
**Specify Device Name**
|
||||
|
||||
If you have multiple device name prefixes for different locations or device use cases, or even a single prefix, you can specify a prefixes.txt file in the `C:\FFUDevelopment\unattend` folder. If the prefixes.txt file is detected and a single prefix is listed, the device will just use that prefix and append the serial number of the device. If there are multiple prefixes listed in the prefixes.txt file, you will be prompted to select which prefix you want to name the device and the serial number will be appended to that prefix. If you want a dash in the name, include the dash in the prefix (e.g. if ABCD- is in the prefixes.txt file, the device name will be ABCD-SerialNumber).
|
||||
Use this option when you want a static device name or a template such as `Comp-%serial%`.
|
||||
|
||||
- With **Copy Unattend.xml**, `%serial%` is resolved during deployment in PE.
|
||||
- With **Inject Unattend.xml**, only static names are supported.
|
||||
- **Copy Unattend.xml** and **Inject Unattend.xml** are mutually exclusive. Select only one.
|
||||
|
||||
**Specify a list of Prefixes**
|
||||
|
||||
This option writes `prefixes.txt` from the list in the UI. Enter one prefix per line or import an existing prefixes file. The source file can use any name because the UI tracks the prefixes path separately. If there is one prefix, deployment uses it automatically. If there are multiple prefixes, the technician is prompted to select one and the serial number is appended to that prefix.
|
||||
|
||||
{: .warning-title}
|
||||
|
||||
|
||||
Reference in New Issue
Block a user