Add a script to push-button reset features
You can customize the Push-button reset experience by configuring extensibility points. This enables you to run custom scripts, install additional applications, or preserve additional user or application data. If you've configured extensibility points in addition to Auto-apply folders, the extensibility points will be used and the Auto-apply folders will be ignored.
To configure extensibility points and customize the Push-button reset experience, you need the following.
- A configuration file named ResetConfig.xml
- Scripts that execute custom operations at selected extensibility points.
- Any additional files required by the scripts
Each script must meet the following requirements:
- Be an executable (.exe) or a command script (.cmd)
- Run without displaying a graphical user interface (GUI)
- Return either 0 to indicate a successful operation, or a non-zero value to indicate an unsuccessful operation
These files should be placed in the folder C:\Recovery\OEM, and will automatically be detected by Push-button reset features. It's OK to use subfolders.
Step 1: Creating Configuration Files to Prepare for Recovery
To create extensibility scripts
In Notepad, you can create custom scripts to save or retrieve log files, check partitions, and to install applications.
Your scripts must meet the following requirements:
- The scripts are formatted as a .cmd or .exe files.
- The scripts do not depend on Windows PE optional components not present in the default Windows RE image (winre.wim).
- The scripts do not depend on binaries (e.g. .exe or .dll files) not present in the default Windows RE image (winre.wim).
- The scripts run without displaying a graphical user interface (GUI).
- The scripts complete all intended functions within 5 minutes for each extensibility point.
- The script must not modify the drive letters. This can potentially cause the recovery to fail.
Your scripts must return a 0 (zero), if successful. If push-button reset receives a non-0 value, the following steps occur:
If running the Refresh your PC feature: All system changes are rolled back. If the script or executable file is initiated from the Windows PC settings menu, the system reboots in Windows. If the script or executable file is initiated from Windows RE or the Boot Options menu, the system remains in Windows RE and displays an error message.
If running the Reset your PC feature: The failure is ignored. The script or executable file proceeds to the next step in the reset process and logs the failure.
You can use the following locations for storage, if needed.
Windows PE RAM drive (X:). This virtual drive is created by Windows PE, and stays active during the Refresh your PC process. You can use it with the Refresh your PC feature to save data before the partition is refreshed, and to restore the data after the partition refresh is complete. The amount of available memory is limited to the amount of RAM on the system, minus the amount of RAM needed for the Windows RE tools when fully expanded. For instructions about mounting Windows RE and determining the fully-expanded file size, see Customize Windows RE.
Designated OEM partition. You can leave extra room on a partition. For example, you can leave room on the recovery image partition, and use scripts to temporarily assign a drive letter and then save files to that partition. However, if your user uses the recovery media to repartition the disks, the data on these partitions might be lost during the recovery process.
**Example 1: Saving Log Files** This example script preserves files that would otherwise be removed, by placing them in a temporary location in memory, to be retrieved by another sample script, **RetrieveLogFiles.cmd**. ``` :rem == SaveLogFiles.cmd :rem == This sample script preserves files that would :rem otherwise be removed by placing them in a :rem temporary location in memory, to be retrieved by :rem RetrieveLogFiles.cmd. :rem == 1. Use the registry to identify the location of :rem the new operating system and the primary hard :rem drive. For example, :rem %TARGETOS% may be defined as C:\Windows :rem %TARGETOSDRIVE% may be defined as C: for /F "tokens=1,2,3 delims= " %%A in ('reg query "HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\RecoveryEnvironment" /v TargetOS') DO SET TARGETOS=%%C for /F "tokens=1 delims=\" %%A in ('Echo %TARGETOS%') DO SET TARGETOSDRIVE=%%A :rem == 2. Copy old logs to a temporary folder in memory mkdir X:\Temp xcopy %TARGETOS%\Logs\*.* X:\temp /cherkyi EXIT 0 ``` **Example 2: Retrieving Log Files** This sample script retrieves the files that were saved in memory by the `SaveLogFiles.cmd` script, and adds them back to the system. It also runs a system diagnostic, and then sends the output to the C:\\Fabrikam folder. ``` :rem == RetrieveLogFiles.cmd :rem == This sample script retrieves the files that :rem were saved in memory by :rem SaveLogFiles.cmd, :rem and adds them back to the system. :rem :rem It also runs a system diagnostic, and sends the output :rem to the C:\Fabrikam folder. :rem == 1. Use the registry to identify the location of :rem the new operating system and the primary drive. :rem :rem %TARGETOS% is the Windows folder :rem (This later becomes C:\Windows) :rem %TARGETOSDRIVE% is the Windows partition :rem (This later becomes C:) for /F "tokens=1,2,3 delims= " %%A in ('reg query "HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\RecoveryEnvironment" /v TargetOS') DO SET TARGETOS=%%C for /F "tokens=1 delims=\" %%A in ('Echo %TARGETOS%') DO SET TARGETOSDRIVE=%%A :rem == 2. Copy the old logs to the new OS :rem at C:\Windows\OldLogs mkdir %TARGETOS%\OldLogs xcopy X:\Temp\*.* %TARGETOS%\OldLogs /cherkyi :rem == 3. Run system diagnostics using the :rem DirectX Diagnostic tool, and save the :rem results to the C:\Fabrikam folders. == mkdir %TARGETOSDRIVE%\Fabrikam %TARGETOS%\system32\dxdiag.exe /whql:off /t %TARGETOSDRIVE%\Fabrikam\DxDiag-TestLogFiles.txt EXIT 0 ```
To create a push-button reset configuration file
In Notepad, create a configuration file (ResetConfig.xml) that points to your push-button reset extensibility scripts. For more information about this file, see ResetConfig XML Reference.
<?xml version="1.0" encoding="utf-8"?> <!-- ResetConfig.xml --> <Reset> <Run Phase="BasicReset_BeforeImageApply"> <Path>SaveLogFiles.cmd</Path> <Duration>4</Duration> </Run> <Run Phase="BasicReset_AfterImageApply"> <Path>RetrieveLogFiles.cmd</Path> <Duration>2</Duration> </Run> <Run Phase="FactoryReset_AfterDiskFormat"> <Path>CheckPartitions.exe</Path> <Duration>2</Duration> </Run> <Run Phase="FactoryReset_AfterImageApply"> <Path>InstallApps.cmd</Path> <Param>/allApps</Param> <Duration>2</Duration> </Run> <!-- May be combined with Recovery Media Creator configurations – insert SystemDisk element here --> </Reset>
Where SaveLogFiles.cmd, RetrieveLogFiles.cmd, CheckPartitions.exe, and InstallApps.cmd are all fictional scripts.
Click File, and then click Save As. In the Encoding box, select UTF-8, and save this file as E:\Recovery\RecoveryImage\ResetConfig.xml.
Where E is the drive letter of a USB flash drive or other removable media. Do not use ANSI coding.
You can use the same ResetConfig.xml file to configure Windows to create recovery media. For more information, see Deploy Push-Button Reset Features.
Step 2: Adding Configuration Files and Scripts to the Destination Computer
To add your configuration files and scripts
On your destination computer, insert the USB flash drive with the configuration files.
Copy the configuration files to the destination computer
Copy E:\Recovery\RecoveryImage\* R:\RecoveryImage\*
where E is the drive letter of the USB flash drive.
Sample script: making sure unattend.xml, LayoutModification.xml, and OOBE.xml are kept during a reset
Windows doesn't automatically save settings created through unattend.xml setup files, nor Windows Start Menu customizations created with LayoutModification.xml during a full-system reset, nor first-login info from oobe.xml. To make sure your customizations are saved, that includes steps to put the unattend.xml, LayoutModification.xml, and oobe.xml files back into place.
Here's some sample scripts that show how to retain these settings and put them back into the right spots.
Save copies of unattend.xml, LayoutModification.xml, oobe.xml, plus these two text files, in C:\Recovery\OEM\.
<?xml version="1.0" encoding="utf-8"?> <!-- ResetConfig.xml --> <Reset> <Run Phase="BasicReset_AfterImageApply"> <Path>EnableCustomizations.cmd</Path> <Duration>2</Duration> </Run> <Run Phase="FactoryReset_AfterImageApply"> <Path>EnableCustomizations.cmd</Path> <Duration>2</Duration> </Run> </Reset>
rem EnableCustomizations.cmd rem Define %TARGETOS% as the Windows folder (This later becomes C:\Windows) for /F "tokens=1,2,3 delims= " %%A in ('reg query "HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\RecoveryEnvironment" /v TargetOS') DO SET TARGETOS=%%C rem Define %TARGETOSDRIVE% as the Windows partition (This later becomes C:) for /F "tokens=1 delims=\" %%A in ('Echo %TARGETOS%') DO SET TARGETOSDRIVE=%%A rem Add back Windows settings, Start menu, and OOBE.xml customizations copy "%TARGETOSDRIVE%\Recovery\OEM\Unattend.xml" "%TARGETOS%\Panther\Unattend.xml" /y copy "%TARGETOSDRIVE%\Recovery\OEM\LayoutModification.xml" "%TARGETOSDRIVE%\Users\Default\AppData\Local\Microsoft\Windows\Shell\LayoutModification.xml" /y xcopy "%TARGETOSDRIVE%\Recovery\OEM\OOBE\Info" "%TARGETOS%\System32\Info\" /s rem Recommended: Create a pagefile for devices with 1GB or less of RAM. wpeutil CreatePageFile /path=%TARGETOSDRIVE%\PageFile.sys /size=256
For multilingual deployments, OOBE.xml uses a more complicated folder structure. It's OK to just copy the entire folder into C:\Recovery\OEM, and then modify the script to copy the entire folder:
xcopy "%ScriptFolder%\Info\" "%TargetOSDrive%\System32\Info\" /s
Now that you have customized the push-button reset experience, you can deploy the recovery image for push-button reset (Install.wim) to the recovery image partition.
To copy the Diskpart script, the ResetConfig.xml file, and the push-button reset recovery image (install.wim) to the recovery image partition of the destination PC, follow the instructions in the Deploy Push-Button Reset Features topic.