Add a Custom Script to Windows Setup
Applies To: Windows 7, Windows Server 2008 R2
Note
This content applies to Windows 7. For Windows 8 content, see Windows Deployment with the Windows ADK.
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 the following way: Setupcomplete.cmd runs after Windows Setup completes, while the RunSynchronous and RunAsynchronous commands run during Windows Setup.
Note
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 completes. This is to ensure that the Group-Policy configuration activity does not interfere with the script.
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 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 completes, Windows Setup exits.
Depending on the phase of Windows Setup, the computer will return to the environment from which Windows Setup was executed (for example, an earlier version of the 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 Files and Folders by Using $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, where temp_folder is the temporary folder you created at the beginning of this step. For example, if you create C:\Temp\SetupFiles\$$\Setup\Scripts\ErrorHandler.cmd, use the following command:setup.exe /m:C:\temp\SetupFilesFor more information about the
setup.exe /mparameter, 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.