Share via

Add a Custom Script to Windows Setup

  • Article

You can add custom scripts to Windows Setup that can be configured to run in different circumstances. You can run a custom script:

  • Immediately after Windows Setup completes.
  • If Windows Setup encounters a fatal error.

Run a Custom Script after Windows Setup Completes

You can make further customizations after Windows Setup completes by adding commands to the %WINDIR%\Setup\Scripts\SetupComplete.cmd file. This file enables you to install additional applications, run custom Windows scripts (cscript/wscript), or make other modifications to the system before a user logs on.

Note

Commands in the Setupcomplete.cmd file are executed with local system privilege.

After Windows is installed, but before the logon screen appears, Windows Setup searches for the SetupComplete.cmd file in the %WINDIR%\Setup\Scripts\ directory.

If a SetupComplete.cmd file is found, the file is executed. Otherwise, installation continues normally. Windows Setup logs the action in the Setupact.log file.

Note

You cannot reboot the system and resume running SetupComplete.cmd.

Setup does not verify any exit codes or error levels in the script after executing SetupComplete.cmd.

The functionality of Setupcomplete.cmd differs from the RunSynchronous and RunAsynchronous commands in that Setupcomplete.cmd runs after Windows Setup completes while the RunSynchronous and RunAsynchronous commands run during Windows Setup.

Run a Custom Script if Windows Setup Encounters a Fatal Error

If Windows Setup encounters a fatal error, you can configure Setup to automatically launch a script that contains custom commands or actions. A fatal error is an error in which Windows Setup is prevented from completing the installation.

This functionality is useful when you automate the installation of many systems at the same time. By enabling this functionality, you can immediately detect when an error occurs during Windows Setup and run custom actions.

If Setup encounters a fatal error and is prevented from completing the installation, Setup searches for a command script in the following directory: %WINDIR%\Setup\Scripts\ErrorHandler.cmd. One of two actions will occur, depending on whether the script is found.

  • If the script is not found, a dialog box is displayed with the error text. A user must dismiss the dialog box before Setup exits.
  • If the script is found, the script executes synchronously. No dialog box or error text is displayed. After the ErrorHandler.cmd script completes, Windows Setup exits.

Depending on the phase of Windows Setup, the computer will return to the environment from which Setup was executed (for example, a downlevel operating system or Windows PE).

There are several ways that you can add the ErrorHandler.cmd file by using the $OEM$ directory structure.

  • Create a Sources\$OEM$\$$\Setup\Scripts folder in the Windows distribution. Copy the ErrorHandler.cmd file to this directory.
    For more information about using $OEM$ files, see Add Content to $OEM$ Folders.

  • Create a temporary folder that contains a $$\Setup\Scripts folder structure. Copy the ErrorHandler.cmd file to this directory, and then run Windows Setup with the /m:temp_folder parameter. For example, if you create C:\Temp\SetupFiles\$$\Setup\Scripts\ErrorHandler.cmd, use the following command:

    setup.exe /m:C:\temp\SetupFiles

    For more information about the setup.exe /m parameter, see Windows Setup Command-Line Options.

There may be instances when Windows Setup encounters more than one error and runs the ErrorHandler.cmd script more than once. When developing the code for ErrorHandler.cmd, ensure that you can run this script multiple times.

See Also

Concepts

Windows Setup Technical Reference