Add a custom tool to the Windows RE Advanced startup menu

Artikel
10/25/2021

You can add a custom troubleshooting or diagnostic tool to the Windows Recovery Environment (WinRE) image. This tool is displayed in the Advanced startup 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.

Add a custom tool

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.

In Notepad, create a configuration file that specifies the custom tool’s filename and parameters (if any):
```
<?xml version="1.0" encoding="utf-8"?>

<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 Advanced startup 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.
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.
Commit your customizations and unmount the WinRE image:
```
Dism /unmount-image /mountdir:C:\mount\winre /commit
```
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.
Unmount and save the changes from the base Windows image:
```
Dism /unmount-image /mountdir:C:\mount\windows /commit
```

Deploy the image

In Notepad, create a configuration file that describes the custom tool in the Advanced startup 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"?>

<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 Advanced startup 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.
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.

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

Note

If you're prompted for a product key, click Skip.
Click Start > PC settings, and then select General.
In the Advanced startup section, select Restart now.

The Windows Advanced startup menu appears.
In the Advanced startup 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.
Confirm that the custom tool works properly, and then close the tool.

If the custom tool does not appear on the Advanced startup 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
```

In the recovery menu, select Troubleshoot, and then click the Fabrikam Utility link.
Confirm that the custom tool works properly, and then close the tool.
Click Continue.

The PC reboots into the operating system.

Windows Recovery Environment (Windows RE) Technical Reference

Customize Windows RE

Deploy Windows RE

Windows RE Troubleshooting Features