Add a Custom Script to Windows Setup

  • Article

Applies To: Windows 8, Windows 8.1, Windows Server 2008 R2, Windows Server 2012, Windows Server 2012 R2

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.

Note

In Windows® 8, oobe.cmd and Setupcomplete.cmd are disabled if an OEM product key is used. This is to ensure that end users reach Start as quickly as possible. Any tools or services that use this infrastructure need to be moved to post Out-Of-Box Experience (OOBE) tasks.

Run a Custom Script after Windows Setup Completes

You can make additional 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. Setupcomplete.cmd functionality differs from the RunSynchronous and RunAsynchronous commands in the following way: Setupcomplete.cmd runs after Windows Setup completes, whereas the RunSynchronous and RunAsynchronous commands run during Windows Setup. Commands in the Setupcomplete.cmd file are executed with local system permission.

To understand the order of operations when adding a custom script after Setup

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

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

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

Note

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

When a computer joins a domain during installation, the Group Policy that is defined in the domain is not applied to the computer until Setupcomplete.cmd is finished. This is to make sure that the Group Policy configuration activity does not interfere with the script.

Run a Custom Script if Windows Setup Encounters a Fatal Error

A fatal error prevents Windows Setup 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 can configure Setup to automatically start a script that contains custom commands or actions to address the cause of the error.

If Windows Setup encounters a fatal error and is prevented from completing the installation, Windows 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 Windows Setup exits.

  • If the script is found, the script executes synchronously. No dialog box or error text is displayed. After the ErrorHandler.cmd script has finished running, Windows Setup exits.

Depending on the phase of Windows Setup, the computer will return to the environment from which Windows Setup was executed, such as an earlier version of the operating system or Windows Preinstallation Environment (Windows PE), for example.

To add and run the ErrorHandler.cmd file

  1. Create a Sources\$OEM$\$$\Setup\Scripts folder in your distribution share. Copy the ErrorHandler.cmd file to this directory. For example:

    Mkdir "C:\$OEM$\$OEM$ Folders\Sources\$OEM$\$$\Setup\Scripts"
Xcopy C:\ErrorHandler.cmd "C:\$OEM$\$OEM$ Folders\Sources\$OEM$\$$\Setup\Scripts"

    For more information, see Manage Files and Folders in a Distribution Share.

  2. Create a temporary folder that contains the $$\Setup\Scripts folder structure. Copy the ErrorHandler.cmd file to this directory. For example:

    Mkdir C:\Temp\SetupFiles\$$\Setup\Scripts
Xcopy C:\ErrorHandler.cmd C:\Temp\SetupFiles\$$\Setup\Scripts

  3. Run Windows Setup with the /m option. For example, if you created C:\Temp\SetupFiles\$$\Setup\Scripts\ErrorHandler.cmd, use the following command:

    Setup /m:C:\Temp\SetupFiles

    For more information about the Setup /m option, 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, make sure that you can run this script multiple times.

See Also

Tasks

Boot from a DVD
Use a Configuration Set with Windows Setup
Deploy a Custom Image
Boot Windows to Audit Mode or OOBE
Add Device Drivers to Windows During Windows Setup

Other Resources

Windows Setup Technical Reference