LTI/ZTI PowerShell: Exit codes

When you run a script in your deployments, it’s good practice to let MDT/SCCM know how the script has ended. This will determine how your task sequence proceeds. You do this by exiting the script with a return code.

I’ve removed some of the enhancements to my Rename-Computer script to demonstrate Exit codes.


Param (
 [String]$Name = $TSEnv:OSDComputername,
 [String]$WorkGroupName
)

Begin{
 Import-Module ZTIUtility
}

Process{
 # Rename the Computer using WMI
 $Result = (Get-WmiObject win32_computersystem).rename($Name)
   If ($Result.ReturnValue -ne 0) {
   Write-Error "Error renaming computer"
   Exit $Result.ReturnValue
 }

# Join a Workgroup
 Add-Computer -WorkGroupName $WorkGroupName -WarningAction SilentlyContinue
 If ($? -eq $false) {
   Write-Error "Error Joining Workgroup"
   Exit 1
 }
}

End{
 Write-Host "The requested operation was successful. Changes will not be effective until the system is rebooted."
 Exit 0
}

There are 2 commands in the script and I’ve handled them differently. If there are no errors then the script will reach the end of the script and exit with the desired exit code.

Why exit with code 0? Well it’s not my choice but if you follow the MSDN – list of system error codes then you’ll see that the success exit code is 0.

ERROR_SUCCESS
  0 (0x0)
  The operation completed successfully.

A reboot is 3010:

ERROR_SUCCESS_REBOOT_REQUIRED
  3010 (0xBC2)
  The requested operation is successful. Changes will not be effective until the system is rebooted.

So why not use 3010 as this script will always require a reboot after a successful execution.? Well, I would but if your script exits with anything else from 0 then MDT gives you a great “Danger! Will Robinson!” at the end.

The 2 commands in the script work differently so I’ve handled them differently. The script passes the rename computer command to a $Results variable and checks that it has returned with a 0. if not then it passes the ReturnValue to the exit code.

With the join workgroup command the script checks that the last command has executed without error by testing the last completed action variable $?. If it is not true then the script exits with the return code 1.

Remember you only have to use Write-Error and non 0 codes if you want fire and brimstone at the end of your deployments, in response to undesired executions.

In some cases, you may wish to simply report the non 0 codes and exit with a friendly Write-Host message.

Additional reading:
Scripting Guy Blogs – Error Handling
Windows PowerShell Exit Codes

Advertisements

About Andrew Barnes

A Scripting and Deployment Specialist.
This entry was posted in MDT 2010, MDT 2012, PowerShell, SCCM, Scripting and tagged , , , . Bookmark the permalink.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s