Pages

Restore: In-Place Upgrade & Hardware Swap

Two scenarios where only some application settings are affected: Windows feature updates that reset certain configurations, and hardware replacements where the user account stays the same but the machine identity changes.

In-Place Windows Upgrade

A Windows feature update or major version upgrade (e.g. Windows 10 → Windows 11) is performed in place. Most application settings survive, but some may be reset or lost — particularly browser defaults, file associations, and certain HKCU registry keys that Windows "refreshes" during the upgrade.

Procedure

Step	Action
1	Pre-upgrade export: Run both machine-level and user-level exports immediately before the upgrade begins.
2	Perform the upgrade.
3	Post-upgrade validation: Run preflight with the pre-upgrade backup to compare the current state against the backup. This reveals which settings were preserved and which were lost.
4	Selective import: Import only the applications whose settings were affected by the upgrade.

Post-Upgrade Validation

:: Preflight to compare current state vs. backup
AppProfileSafe.CLI.exe --preflight --import ^
  --manifestFile "\\server\backups\%COMPUTERNAME%\%USERNAME%\Manifest.xml" ^
  --apps "Firefox-User,Office-User,Chrome-User" ^
  --unc-credential-store --silentMode

Review the preflight JSON report in the report folder to determine which applications have differences. Then import only the affected apps:

:: Import only apps that were affected by the upgrade
AppProfileSafe.CLI.exe --import ^
  --manifestFile "\\server\backups\%COMPUTERNAME%\%USERNAME%\Manifest.xml" ^
  --apps "Firefox-User,Chrome-User" ^
  --unc-credential-store --silentMode --ignoreRestorePointLimit

No mapping needed: Same machine, same user, same paths. The upgrade does not change directory structures or usernames.

Hardware Swap

A user's hardware is replaced — laptop swap, desktop replacement, docking station change — but the username and domain remain the same. The new machine has a different hostname.

Key Differences from a Fresh Build

No username mapping needed — same user, same domain.
Machine name mapping may be needed if any app definitions store the hostname in registry values or file content.
Drive letter mapping may be needed if the disk layout differs (e.g. source had a D: drive, target does not).
Software is typically pre-installed on the new machine before the user receives it.

Import Commands

:: Machine import (as admin, before user logon if possible)
AppProfileSafe.CLI.exe --import ^
  --manifestFile "\\server\backups\OLD-LAPTOP\Machine\Manifest.xml" ^
  --apps "Firefox-Machine,Office-Machine" ^
  --mappingFile "\\server\mappings\hardware-swap.xml" ^
  --unc-credential-store --silentMode --ignoreRestorePointLimit

:: User import (after logon, with delay)
AppProfileSafe.CLI.exe --import ^
  --manifestFile "\\server\backups\OLD-LAPTOP\%USERNAME%\Manifest.xml" ^
  --apps "Firefox-User,Office-User,Chrome-User" ^
  --unc-credential-store --silentMode --ignoreRestorePointLimit

If drive letters and directory structures are identical, the mapping file can be omitted.

Minimal Mapping File Example

A mapping file for a hardware swap where only the hostname changed:

<?xml version="1.0" encoding="utf-8"?>
<Mappings xmlns="urn:appprofilesafe:mappings:v1">
  <RegistryMappings>
    <Mapping From="OLD-LAPTOP" To="NEW-LAPTOP" />
  </RegistryMappings>
</Mappings>

See What Is a Mapping File? for the full schema.