Run custom actions during feature update

Overview

IT Professionals can customize a feature update by running their own custom action scripts during and after a feature update. Custom actions are available starting with Windows 10, version 1803.

Running custom actions

About custom actions

Custom actions are .cmd scripts that run during the feature update process. These can be run during four phases of a feature update:

  1. Pre-install phase: This phase is when Setup starts, but prior compatibility checks. Actions during this phase are specified in preinstall.cmd. If the scripts fail, the feature update will fail.
  2. Pre-commit phase: This phase is prior to the feature update being applied and the system rebooting. Actions during this phase are specified in precommit.cmd. If the scripts fail, the feature update will fail.
  3. Post-uninstall phase: This phases is after a user initiates an uninstall of a feature update. Actions during this phase are specified in postuninstall.cmd. postuninstall.cmd is new for Windows 10, version 2004.
  4. Completion: This phase is after Setup completes. If the feature update fails or has to be rolled back, failure.cmd can be used to perform custom operations or undo actions of previous custom scripts. If the feature update succeeds, success.cmd can be used to perform post feature update actions. success.cmd is new for Windows 10, version 2004.

Custom actions folder structure

Custom action scripts run from subfolders in %windir%\System32\update\, depending on whether you want scripts to run for a single upgrade or on all future upgrades. Windows Setup automatically looks for these scripts in the following locations, and will run them if they are present:

Folder Description
%windir%\System32\update\run Windows Setup will migrate scripts in these folders so they are run in future upgrades.
%windir%\System32\update\runonce Scripts in this folder will only run in one upgrade and won't be migrated for future upgrades.
%windir%\System32\update\run\<GUID>

%windir%\System32\update\runonce\<GUID>
Create a unique GUID to clearly identify each script you run. Use this GUID to name a folder within the run and runonce folders.
%windir%\System32\update\run\<GUID>\reflectdrivers

%windir%\System32\update\runonce\<GUID>\reflectdrivers
Boot-critical drivers in this folder will be reflected. Make sure the reflectdrivers folder only contains a necessary set of encryption drivers. Having more drivers than necessary can negatively impact upgrade scenarios. See Device drivers to learn more about reflected drivers.

If an update fails or has to be rolled back, a failure.cmd script can be used to perform custom operations or undo actions of previous custom scripts. If the scripts fail, the update will fail.

Custom action script locations and examples

Script locations

The following table shows the folder path structure of files for running custom actions:

Run (Scripts will be migrated) Run Once (scripts won't be migrated)
%windir%\System32\update\run\<GUID>\preinstall.cmd %windir%\System32\update\runonce\<GUID>\preinstall.cmd
%windir%\System32\update\run\<GUID>\precommit.cmd %windir%\System32\update\runonce\<GUID>\precommit.cmd
%windir%\System32\update\run\<GUID>\postuninstall.cmd %windir%\System32\update\runonce\<GUID>\postuninstall.cmd
%windir%\System32\update\run\<GUID>\success.cmd %windir%\System32\update\runonce\<GUID>\success.cmd
%windir%\System32\update\run\<GUID>\failure.cmd %windir%\System32\update\runonce\<GUID>\failure.cmd
%windir%\System32\update\run\<GUID>\reflectdrivers\example1.inf %windir%\System32\update\runonce\<GUID>\reflectdrivers\example2.inf
%windir%\System32\update\run\<GUID>\reflectdrivers\example1.sys %windir%\System32\update\run\<GUID>\reflectdrivers\example2.sys

Example file paths and names

Scenarios File location examples
Script deployment data %windir%\system32\update\
Migration directories
Scripts that will be migrated %windir%\system32\update\run\
Scripts that won't be migrated %windir%\system32\update\runonce\
Folder path with a GUID %windir%\system32\update\run\6971CB27-6F59-43CD-A764-969EE9BBCC1C\
Script names with GUID
%windir%\system32\update\run\6971CB27-6F59-43CD-A764-969EE9BBCC1C\preinstall.cmd
%windir%\system32\update\run\6971CB27-6F59-43CD-A764-969EE9BBCC1C\precommit.cmd
%windir%\system32\update\run\6971CB27-6F59-43CD-A764-969EE9BBCC1C\postuninstall.cmd
%windir%\system32\update\run\6971CB27-6F59-43CD-A764-969EE9BBCC1C\failure.cmd
%windir%\system32\update\run\6971CB27-6F59-43CD-A764-969EE9BBCC1C\success.cmd
%windir%\system32\update\runonce\6971CB27-6F59-43CD-A764-969EE9BBCC1C\preinstall.cmd
%windir%\system32\update\runonce\6971CB27-6F59-43CD-A764-969EE9BBCC1C\precommit.cmd
%windir%\system32\update\runonce\6971CB27-6F59-43CD-A764-969EE9BBCC1C\postuninstall.cmd
%windir%\system32\update\runonce\6971CB27-6F59-43CD-A764-969EE9BBCC1C\failure.cmd
%windir%\system32\update\runonce\6971CB27-6F59-43CD-A764-969EE9BBCC1C\success.cmd
Reflected drivers folder %windir%\system32\update\run\6971CB27-6F59-43CD-A764-969EE9BBCC1C\reflectdrivers\