Exit-PSScript

Description

Ends a PowerPack script with a specific exit code, logging the outcome before the script terminates. Every install/uninstall script must end by calling Exit-PSScript — either explicitly in your own code, or implicitly through the #### MAIN #### block of the script template, which always calls it as the very last step (Exit-PSScript 0 on success, or Exit-PSScript $_.Exception.HResult from the catch block on an unhandled error).

Important

Calling Exit-PSScript with exit code 3010 does not terminate the script. The call returns immediately and the rest of your function keeps running. This exists so that a 3010 result from an installer mid-script doesn’t cut PostInstall or later steps short — see Reboot handling below for the correct way to signal “success, reboot required.”

Syntax

Exit-PSScript -exitcode <int> -exitmessage <string>

Parameters

exitcode (Int32)

Mandatory. The exit code to end the script with. Use one of the predefined exit codes below, or an external installer’s own exit code passed straight through on failure (see $cs.Shell_Execute). Don’t invent your own numeric codes for things you control yourself — use 1 for a controlled failure in your own prerequisite/logic checks.

exitmessage (String)

Optional. A message written to the log immediately before the exit code is processed. Use this instead of a separate $cs.Job_WriteLog call right before Exit-PSScript — passing both logs the same information twice.

Predefined exit codes

These are the exit codes recognized and handled specially by CapaOne and the PowerPack agent. Don’t use any other numeric code as a deliberate “control” code — an external installer’s own failure code (e.g. 1603) is the one exception, and should be passed straight through rather than remapped to one of these.

Code	Name	Meaning
0	SUCCESS	Success
3010	SUCCESS_REBOOT_REQUIRED	Success, reboot required
3011	SUCCESS_RESTART_REQUIRED	Success, restart required
3326	PACKAGE_CANCELLED_RETRY_LATER	Cancel, retry later
3330	PACKAGE_ALREADY_INSTALLED	Already installed

Reboot handling

To signal that a reboot is required, call $cs.Job_RebootWS at the point where you discover it’s needed, then let the script finish normally and end with Exit-PSScript 0 — do not try to end the script with Exit-PSScript 3010 yourself, since (as noted above) that call doesn’t actually terminate the script. When $cs.Job_RebootWS has been called and the script ends with exit code 0, CapaInstaller takes care of the actual reboot for you. If the script ends with any other exit code, CapaInstaller doesn’t reboot the computer.

For an installer that reports 3010 on its own (meaning the installer itself wants a reboot), treat it as success rather than failure, and optionally call $cs.Job_RebootWS so the reboot is properly signalled:

• PowerShell

$Result = $cs.Shell_Execute("msiexec.exe", $Arguments)
if ($Result -ne 0 -and $Result -ne 3010) {
    $cs.Job_WriteLog("Installation failed with exit code: $Result")
    Exit-PSScript $Result
}
if ($Result -eq 3010) {
    $cs.Job_RebootWS("Reboot required after installation")
}

Example

• PowerShell

# Success
Exit-PSScript 0

# Controlled failure from your own prerequisite check
$cs.Job_WriteLog("Minimum required disk space not available")
Exit-PSScript 1

# Passing an external installer's own failure code straight through
$cs.Job_WriteLog("MSI installation failed with exit code: $Result")
Exit-PSScript $Result

# Exit with a message logged in the same call
Exit-PSScript -exitcode 3330 -exitmessage "Application is already installed"

Related functions

$cs.Job_RebootWS $cs.Job_WriteLog $cs.Shell_Execute