Add a Script to Push-Button Reset Features

Article
02/10/2014

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.

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](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.

Add a Script to Push-Button Reset Features

Prerequisites

Step 1: Creating Configuration Files to Prepare for Recovery

To create extensibility scripts

To create a push-button reset configuration file

Step 2: Adding Configuration Files and Scripts to the Destination Computer

To add your configuration files and scripts

Next Steps

See Also

Tasks

Reference

Concepts

Additional resources