Windows build customization scripts

This section describes creating build customization scripts for Microsoft Windows.

Windows build process (WinPE boot iImage)

The following table details the steps that occur when you provision an installation client with Windows WinPE.

A user initiates the build process with Steps 1 and 6. The rest of the build process steps happen automatically in OS Provisioning.

Microsoft Windows build process (WinPE)

Phase	Build Process Steps
Pre-installation	A user boots an installation client over the network by using a PXE network bootstrap program or by using the WinPE. The user can install either WinPE x86 32 bit or WinPE x64 64 bit pre-installation environment. PXE boots the Windows OS Build Agent over the network. When using the WinPE pre-installation environment, you will not be prompted to create a disk partition. The OS Build Agent collects pertinent hardware information and registers the information with SA. The server is ready to be provisioned and is available for selection from the Unprovisioned Servers in the SA Client.
Phase One	5. The user selects a Windows server from the Unprovisioned Servers list in the SA Client and runs an OS Sequence on the server. The Windows build script mounts the Windows installation media as indicated by the Media Resource Location (MRL). The Windows build script initiates a Windows unattended setup. The Windows build script waits for a Windows unattended setup to complete and Windows to boot for the first time.
Phase Two	Windows boots for the first time. If a build customization script was specified in the OS Installation Profile, it is executed by the Windows build script. The Windows build script installs the Agent. The Windows build script exits and Phase Two is complete.

Legacy build customization script run.bat

In previous releases of SA, OS Provisioning supported a single hook script named run.bat. If you choose to use this legacy script, it will still work, but it will only call the Pre-Agent hook.

For example, if the cabinet file does NOT contain a runphase.bat script at the root level, but it DOES contain a run.bat script at the top level, it will be treated as a legacy single-hook script. It will NOT be run at the “Pre-Copy” phase. It is run only at the Pre‑Agent phase with no command line arguments.

If the cabinet file contains both runphase.bat and run.bat, it will still be treated as multi-phase and run.bat will be ignored.

Creating a Windows build customization script (WinPE)

Windows WinPE customization scripts support the following installation hooks:

• Pre-Partition
• Pre-ShareConnect
• Pre-Copy
• Post-Copy
• Pre-Reboot
• Pre-Agent
• Post-Agent

The following conventions also apply:

• WinPE Windows build customizations must be in the form of a zip file.
• There must be a run.cmd script in the root of the zip file. See the example run.cmd below.
• Hooks are unpacked in %systemdrive%\opswba\hook (for example, x:\opswba\hook).
  • Hooks are unpacked recursively and will overwrite existing files.
  • Hooks are transferred and unpacked only once during the initial phase. Subsequent runs do not require unpacking. Hooks will be transferred and unpacked again after reboots (for example, before Pre-Agent), at which point they are unpacked in %systemdrive%\opswba\hook (typically c:\opswba\hook).
  • When hooks are executed, the current directory will be the root directory of the unpacked zip file.
• In order to identify which phase of the build customization is being run, the build scripts pass a single command line argument to the run.cmd script, matching the name of the hook phase (Pre-Copy, Post-Copy, etc.). See the example run.cmd below.
• The build interprets a non-zero return code from a customization (hook) phase as a fatal error. Therefore, ensure that the appropriate code is returned. In the event of a fatal error, the directory in which the build customization was unpacked will be left as is (to aid in debugging). This type of error is one of the few errors during the early phases of the provisioning process from which auto-recovery is not possible.
• Any output from the build customization (hook) phase will be recorded in the build log. Therefore, it is important to ensure that no inappropriately sensitive information is contained in the output.
• Upon completion of the last build customization hook (Post-Agent), the hook directory will be forcibly deleted along with all its contents.
• After running each hook, buildscripts look for a file called %temp%\skipnextstep. If this file exists, it will be deleted and the next step of the provisioning will be bypassed. The following is what is bypassed for each build customization phase if the skipnextstep file exists:
  • Pre-Partition
    • skips partitioning and formatting
  • Pre-ShareConnect
    • skips connecting Z: to the media server share
  • Pre-Copy
    • skips launching the build and monitoring it altogether
  • Post-Copy
    • skips copying the Agent and installing the boot agent (not recommended)
  • Pre-Reboot
    • skips the reboot (not recommended)
  • Pre-Agent
    • skips the agent install
  • Post-Agent
    • skipnextstep has no effect (the file will be deleted)

Sample run.cmd file

This section shows a sample, minimal run.cmd. This sample simply echoes to the console for each hook phase. To manually test this hook from a command shell, execute it using:

cmd /c run.cmd

which mimics the build agent environment as closely as possible (and prevents an “exit” in the script from causing an exit from your command shell).

@echo off

if x%1 == xPre-Partition (

call :PrePartition

) else if x%1 == xPre-ShareConnect (

call :PreShareConnect

) else if x%1 == xPre-Copy (

call :PreCopy

) else if x%1 == xPost-Copy (

call :PostCopy

) else if x%1 == xPre-Reboot (

call :PreReboot

) else if x%1 == xPre-Agent (

call :PreAgent

) else if x%1 == xPost-Agent (

call :PostAgent

)

goto :end

 

:PrePartition

echo We are in the Pre-Partition hook phase

exit 0

 

:PreShareConnect

echo We are in the Pre-ShareConnect hook phase

exit 0

 

:PreCopy

echo We are in the Pre-Copy hook phase

exit 0

 

:PostCopy

echo We are in the Post-Copy hook phase

exit 0

 

:PreReboot

echo We are in the Pre-Reboot hook phase

exit 0

 

:PreAgent

echo We are in the Pre-Agent hook phase

exit 0

 

:PostAgent

echo We are in the Post-Agent hook phase

exit 0

 

:end