Add a Custom Tool to the Windows RE Boot Options Menu

  • Article

Applies To: Windows 8.1, Windows Server 2012, Windows Server 2012 R2

You can add a custom troubleshooting or diagnostic tool to the Windows RE image. This tool is displayed in the Boot Options menu.

By developing your custom tool to run in Windows RE, you can leverage the touch and on-screen keyboard support available in Windows RE.

To add a custom tool

  1. Extract and mount a Windows image (install.wim) and its corresponding Windows RE image (winre.wim):

    md c:\mount
xcopy D:\sources\install.wim C:\mount 
md C:\mount\windows
Dism /mount-image /imagefile:C:\mount\install.wim /index:1 /mountdir:C:\mount\windows 
md C:\mount\winre 
Dism /mount-image /imagefile:c:\mount\windows\windows\system32\recovery\winre.wim /index:1 /mountdir:C:\mount\winre

    For more information about these steps, see the topic: Customize Windows RE.

  2. In Notepad, create a configuration file that specifies the custom tool’s filename and parameters (if any):

    <?xml version="1.0" encoding="utf-8"?>
<!-- WinREConfig.xml -->
<Recovery>
   <RecoveryTools>
      <RelativeFilePath>OEMDiagnostics.exe</RelativeFilePath>
      <CommandLineParam>/param1 /param2</CommandLineParam>
   </RecoveryTools>
</Recovery>

    Where C:\Tools\OEMDiagnostics.exe is the custom troubleshooting or diagnostics tool, and where /param1 and /param2 are optional parameters used when running this custom tool.

Note

You can only add one custom tool to the Windows RE boot options menus. 

Save the file using UTF-8 coding. Do not use ANSI:

Click **File**, and then click **Save As**. In the **Encoding** box, select **UTF-8**, and save this file as `C:\mount\WinREConfig.xml`

  1. Create a \Sources\Recovery\Tools folder in the Windows RE mount folder, and then copy the custom tool and its configuration file into the new folder:

    md C:\mount\winre\sources\recovery\tools
copy C:\Tools\OEMDiagnostics.exe C:\mount\winre\sources\recovery\tools
copy C:\mount\WinREConfig.xml C:\mount\winre\sources\recovery\tools

  2. Commit your customizations and unmount the Windows RE image:

    Dism /unmount-image /mountdir:C:\mount\winre /commit

  3. Optional: make a backup copy of the Windows RE image.

    copy C:\mount\windows\windows\system32\recovery\winre.wim C:\mount\winre_amd64_backup.wim

    You can often reuse the same customizations on multiple images.

  4. Unmount and save the changes from the base Windows image:

    Dism /unmount-image /mountdir:C:\mount\windows /commit

To deploy the image

  1. In Notepad, create a configuration file that describes the custom tool in the boot options menu. Add descriptions for each language you support. This example specifies both English and French language versions of the tool name and description.:

    <?xml version="1.0" encoding="utf-8"?>
<!-- AddDiagnosticsToolToBootMenu.xml -->
<BootShell>
   <WinRETool locale="en-us">
         <Name>Fabrikam Utility</Name>
         <Description>Troubleshoot your Fabrikam PC</Description>
   </WinRETool>
   <WinRETool locale="fr-fr">
      <Name>Utilité de Fabrikam</Name>
      <Description>Dépannez votre PC de Fabrikam</Description>
   </WinRETool>
</BootShell>

Warning

Limit the <Name> and <Description> values to approximately 30 characters or less to make sure that they appear correctly in the boot options menu. 

Save the file using UTF-8 coding:

Click **File**, and then click **Save As**. In the **Encoding** box, select **UTF-8**, and save this file as `E:\Recovery\BootMenu\AddDiagnosticsToolToBootMenu.xml`

Where *E:\\* is the drive letter of a removable drive or network location.

  1. On your destination computer, during image deployment, but after you register the custom Windows RE boot image and the Windows operating system, you must register the description of the custom tool:

    Reagentc /setbootshelllink /configfile E:\Recovery\BootMenu\AddDiagnosticsToolToBootMenu.xml

    If the custom tool is registered properly, the output from running this command will be: <OEM Tool =  1>.

Note

For more information about deploying Windows, see the Deploy Windows RE topic.

To verify the custom tool appears in the Boot Options menu when launched from Windows

  1. Restart the destination computer, and complete OOBE as your user.

Note

If you are prompted for a product key, click Skip.

  1. Click Start > PC settings, and then select General.

  2. In the Advanced startup section, select Restart now.

    The Windows Boot Options menu appears.

  3. In the Boot Options menu, select Troubleshoot, and then click the Fabrikam Utility link.

    The computer restarts in Windows RE, and the tool that is specified in the <RecoveryTools> section of the WinREConfig.xml file, appears.

  4. Confirm that the custom tool works properly, and then close the tool.

    If the custom tool does not appear on the Boot Options menu, you can try the following:

    • Verify the WinREConfig.xml and the AddDiagnosticsToolToBootMenu.xml files are saved using the UTF-8 encoding format.

    • Disable Windows RE, register the custom tool again, and then enable Windows RE. For example:

      Reagentc /disable 
Reagentc /setbootshelllink /configfile E:\Recovery\BootMenu\AddDiagnosticsToolToBootMenu.xml
Reagentc /enable

To verify the custom tool appears in the Windows RE recovery menu

  1. In the recovery menu, select Troubleshoot, and then click the Fabrikam Utility link.

  2. Confirm that the custom tool works properly, and then close the tool.

  3. Click Continue.

    The PC reboots into the operating system.

See Also

Tasks

Customize Windows RE
Deploy Windows RE

Reference

Windows RE Troubleshooting Features

Concepts

Windows Recovery Environment (Windows RE) Overview