Walkthrough: Customize Push-Button Reset

  • Article

Applies To: Windows 8

[This topic is pre-release documentation and is subject to change in future releases. Blank topics are included as placeholders.]

Push-button reset is a built-in recovery tool that permits end users to recover the operating system while preserving their data, without having to back up their data in advance. Further, you can customize the push-button reset experience for your end users to preserve important customizations and perform additional functionality at available extensibility points.

In this topic:

  • Overview

  • Create Extensibility Scripts

  • Create a ResetConfig.xml Configuration File

Prerequisites

To complete this walkthrough, you need the following:

  • A technician computer that is running Windows® 8. A technician computer must have the Windows® Assessment and Deployment Kit (Windows ADK) installed.

Overview

In addition to the efficiencies that the push-button reset tool offers, you can customize the push-button reset experience for your end users by inserting custom scripts and executable files at available extensibility points.

The following diagram shows the two extensibility points (A and B) where you can add custom operations when the end user runs the Refresh your PC feature.

Refresh your PC Extensibility Points

Extensibility points for the Refresh your PC feature

Extensibility point System state Sample use

A

User settings and data that you want to migrate are moved to a temporary location.

Copy system files, applications, or settings that are not migrated by default.

B

The factory image has been applied from the recovery partition to the root of the Windows partition. Only critical system settings have been migrated.

Restore the system files, applications, or settings that you copied at extensibility point A.

The following diagram describes the two extensibility points (C and D) where you can add custom operations when the end user runs the Reset your PC feature.

Reset your PC Extensibility Points

Extensibility points for the Reset your PC feature

Extensibility point System state Sample use

C

The Windows and data partitions (optional) have been formatted.

Prepare the hard drive partitions before the factory image is applied. For example, detect whether the end user has made changes to the partition layout, and reconfigure the partition layout in these cases.

> [!NOTE] > The Windows partition GUID must remain the same. >

D

The factory image has been applied from the recovery partition to the root of the Windows partition.

Restore the system files, applications, or settings that you copied at extensibility point A.

Step 1: Create extensibility scripts

  1. Create scripts (.cmd files) or executables (.exe files) to execute at the available extensibility points (A or B) when the Refresh your PC feature runs. For example:

    1. At extensibility point A, BasicReset_BeforeImageApply, to copy files.

    2. At extensibility point B, BasicReset_AfterImageApply, to install custom applications.

  2. Create scripts or executables to execute at the available extensibility points (A or B) when the Reset your PC feature runs. For example:

    1. At extensibility point C, FactoryReset_AfterDiskFormat, to fix partitions.

    2. At extensibility point D, FactoryReset_AfterImageApply, to install custom applications.

  3. Ensure that the custom scripts and executable files meet the following requirements:

    • Be in the form of 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-0 value to indicate an unsuccessful operation.

    • Be able to complete all intended functions within 5 minutes per extensibility point.

    The following table details how push-button reset handles return codes.

    Push-button reset feature Extensibility point 0 return value Non-0 return value

    Refresh your PC

    A

    Proceed to the next step in the refresh process.

    If the script or executable is initiated from PC settings, the system restarts to Windows. If the script or executable is initiated from the Windows RE or boot option menus, the system remains in Windows RE and displays an error message.

    B

    Proceed to the next step in the refresh process.

    All changes to the system are rolled back. If the script or executable is initiated from PC settings, the system restarts to Windows. If the script or executable is initiated from the Windows RE or boot option menus, the system remains in Windows RE and displays an error message.

    Reset your PC

    C

    Proceed to the next step in the reset process.

    The failure is ignored. The script or executable proceeds to the next step in the reset process and logs the failure.

    D

    Proceed to the next step in the reset process.

    The failure is ignored. The script or executable proceeds to next step in the reset process and logs the failure.

    In the next step, you create a ResetConfig.xml configuration file. The following example specifies the location of sample scripts that you created for the two **Refresh your PC** extensibility points and the two **Reset your PC** extensibility points. where *\
    1. Save the scripts to a network location, or USB flash drive.

    Step 2: Create a ResetConfig.xml configuration file

    After you have created the custom scripts at the available push-button reset extensibility points, you must register the extensibility points by creating a configuration file that is named ResetConfig.xml. You must place the ResetConfig.xml file in the same folder as the push-button reset recovery image (Install.wim).

    1. Create an .xml file by using the following syntax. This example sets a custom script to run during reset by using the <Run> element.

      <?xml version="1.0" encoding="utf-8"?>
   <Reset>
      <Run phase>=<ExtPoint>
         <Path><PathToScript></Path>
         <Duration><TimeEstimate></Duration>
         <Param><Parameters></Param>
      </Run>
   </Reset>

      where <ExtPoint> is the extensibility point, <PathToScript> is the location of the script that you want to run, <TimeEstimate> is the estimated time that the script referenced at a particular extensibility point will take to run, and <Parameters> are the command-line parameters that are used when you execute the custom script or executable file.

      Important

      If you use a text editor to author .xml files, save the document with an .xml file name extension and use UTF-8 encoding. Do not use ANSI.

    2. Select the customizations that you intend to enable by including the corresponding elements in your ResetConfig.xml file. The following table describes the XML elements for a custom script or executable to run.

      Element Description

      <Run phase=<ExtPoint>>

      ...

      </Run>

      Each <Run> section defines the extensibility point to be used, the script that is executed at that extensibility point, and estimated duration in minutes.

      The phase attribute is mandatory. It accepts only the following values for <ExtPoint>:

      • BasicReset_BeforeImageApply – Runs the specified program at extensibility point A

      • BasicReset_AfterImageApply – Runs the specified program at extensibility point B

      • FactoryReset_AfterDiskFormat – Runs the specified program at extensibility point C

      • FactoryReset_AfterImageApply – Runs the specified program at extensibility point D

      You can specify up to four <Run> sections in a single ResetConfig.xml file. However, each <Run> section must contain a different <ExtPoint> value for the phase attribute.

      <Path><PathToScript></Path>

      Specifies the location of the script for a particular <Run> section.

      <PathToScript> must be the relative path of the script from the folder that contains the Install.wim and ResetConfig.xml files on the recovery image partition.

      > [!NOTE] > The read and write permission of the specified scripts and executable files and their dependencies should be set to require administrative user rights. >

      <Duration><TimeEstimate></Duration>

      Specifies the estimated time in minutes that the extensibility point will take to run. <TimeEstimate> must be an integer. The value must be between 1 and 5.

      <Param><Parameters></Param>

      Specifies command-line parameters to use when you execute the custom script or executable file. <Parameters> is treated as a string, and can contain multiple parameters.

    3. Save the ResetConfig.xml file.

    4. To copy the ResetConfig.xml file to the recovery image partition of the destination computers together with the push-button reset recovery image (Install.wim), follow the instructions in Walkthrough: Configure Push-Button Reset.

    The ResetConfig.xml file and push-button reset recovery image (Install.wim) must reside in the same folder on the recovery image partition. For each registered extensibility point, push-button reset first searches for customizations, such as custom scripts and executable files, in the \sources\recovery\tools path on the Windows RE tools partition. Push-button reset then searches the recovery image partition.

    Next Steps

    Now that you have customized the push-button reset experience at available extensibility points, you can deploy the push-button reset recovery image (Install.wim) to the recovery image partition. For more information, see Walkthrough: Configure Push-Button Reset.

    See Also

    Tasks

    How to Customize a Windows RE Boot Image
    Walkthrough: Create Windows Recovery Media
    Walkthrough: Customize Push-Button Reset

    Reference

    REAgentC Command-Line Options

    Concepts

    Windows RE Overview