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:
- 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. - 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. - 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.cmdis new for Windows 10, version 2004. - Completion: This phase is after Setup completes. If the feature update fails or has to be rolled back,
failure.cmdcan be used to perform custom operations or undo actions of previous custom scripts. If the feature update succeeds,success.cmdcan be used to perform post feature update actions.success.cmdis new for Windows 10, version 2004.
Custom actions run during a feature update that is installed by Windows Setup. Some Windows feature updates are installed via a monthly quality update, and later turned on through an “enablement package,” a small, quick-to-install “master switch” that activates the Windows features. For example, updating from Windows 10, version 2004 to Windows 10, version 20H2. Custom actions are not supported for feature updates that are installed via enablement packages.
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\ |