Add a custom tool to the Windows RE boot options menu

You can add a custom troubleshooting or diagnostic tool to the Windows Recovery Environment (WinRE) image. This tool is displayed in the Boot Options menu.

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

New for Windows 10: You won't be able to add WinRE optional components that aren't already in the default WinRE tools. For example, if you have a app from Windows 8 that depended on the .NET optional components, you'll need to rewrite the app for Windows 10.

To add a custom tool

  1. Extract and mount a Windows image (install.wim) and its corresponding WinRE 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 WinRE 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.

  3. Create a \Sources\Recovery\Tools folder in the WinRE 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
    

    The custom tool and any associated folders must be in this folder so that it can continue to work after future WinRE upgrades.

  4. Commit your customizations and unmount the WinRE image:

    Dism /unmount-image /mountdir:C:\mount\winre /commit
    
  5. Optional: make a backup copy of the WinRE 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.

  6. 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.

  2. On your destination computer, during image deployment, but after you register the custom WinRE 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.

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

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

    The Windows Boot Options menu appears.

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

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

  5. 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 WinRE, register the custom tool again, and then enable WinRE. For example:

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

      To verify the custom tool appears in the WinRE recovery menu

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

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

  8. Click Continue.

    The PC reboots into the operating system.

Related topics

Windows Recovery Environment (Windows RE) Technical Reference

Customize Windows RE

Deploy Windows RE

Windows RE Troubleshooting Features