Add a Script to Push-Button Reset Features
Applies To: Windows 8, Windows 8.1
You can customize the push-button reset experience by adding scripts, also known as push-button reset extensibility scripts. For example, you can use scripts to preserve important customizations or perform system diagnostics when the Refresh your PC or Reset your PC features run. You can add scripts at multiple points in the recovery process. For more information, see the Push-Button Reset Overview topic.
These extensibility points are intended for basic operations such as copying files or injecting drivers.
Prerequisites
- Before you can create the push-button reset extensibility scripts, we recommend that you complete Deploy Push-Button Reset Features.
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.
Important
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.
- 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.
- 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](https://technet.microsoft.com/en-us/library/retrievelogfiles.cmd\(v=Win.10\)).
: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 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 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.
Note
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.
Next Steps
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.
See Also
Tasks
Create Media to Run Push-Button Reset Features
Deploy Push-Button Reset Features
Reference
REAgentC Command-Line Options
ResetConfig XML Reference