close

Home

PowerShell

How to Use the PowerShell Exit Keyword to Terminate Scripts

Ivan Mirchev

|
PowerShell

PowerShell’s built-in exit keyword allows you to terminate scripts without closing your PowerShell session. There are different ways to use PowerShell exit to break the execution of a script, function, loop, or switch statement. But it’s important to understand how the exit keyword works if you want to use it effectively.

In this guide, I will explain how you can also use the break and return keywords to control the execution of your code in PowerShell. Each of these methods has its own use cases, so keep reading if you want to know more!

How to use the PowerShell exit keyword

The PowerShell exit keyword is used to exit what’s running in the console. Depending on what you’re doing, this could either be a script or your current PowerShell console session.

Closing the PowerShell console with exit

If you open a PowerShell console session and type exit, the console session will terminate.

The exit keyword terminates our console session

Terminating a PowerShell script with exit

If you execute the exit keyword inside of a PowerShell script, it will only terminate the script and the commands that follow it won’t be executed.

Write-Host Script Start
Write-Host Executing exit command
exit
Write-Host Script End

After running the exit command here, the script was indeed terminated. We returned to the PowerShell console session and the rest of the commands were not executed.

The exit keyword terminates our PowerShell script

Understanding PowerShell exit codes

When the exit command is executed successfully, it returns an exit code:

  • 0 means normal termination.
  • While 1 means failure.

The error code result is stored in the PowerShell built-in variable – $LASTEXITCODE.

If we check the exit code for our last example, we can confirm that it was completed successfully:

The exit code 0 confirms the normal termination

The full list of System error codes can be found in this Microsoft support article.

Setting up custom error codes

You can also set custom error codes for PowerShell exit. They will need to be an integer value.

On Windows, this could be any number between [int]::MinValue and [int]::MaxValue. On Unix-based systems, however, you may only use positive numbers between [byte]::MinValue and [byte]::MaxValue.

For example, if you want to return 5 as a custom exit code, you should provide it as an argument to the exit keyword:

Write-Host Script Start
Write-Host Executing exit command with exit code 5
exit 5
Write-Host Script End
If you want to return 5 as a custom exit code, you should provide it as an argument to the exit keyword:

Exit codes can be interpreted even when executing a PowerShell script from a command prompt. In this case, the result is stored in the variable %ERRORLEVEL%.

The result of an exit code is stored in the variable %ERRORLEVEL%

How to use the PowerShell break keyword

The break keyword allows you to break out of PowerShell loops or switch cases. If break is executed in a script outside of a loop or switch statement, it will escape the script. However, if break is executed in a nested loop, it will only stop that loop and not the parent.

If we use our previous script example and replace the exit keyword with break, we’ll escape the script and none of the commands that follow it will be executed:

Write-Host Script Start
Write-Host Executing break command
break
Write-Host Script End
The break keyword is used to escape the script

If we use break inside of a loop, the loop will stop, but PowerShell will continue to execute the rest of the script.

Write-Host Script Start
$NumberList = 1..5
foreach ($number in $NumberList) {
    Write-Host The current number is $number
    break
}
Write-Host Commands after the loop
Write-Host Script End 
The break keyword can also stop a loop

In the example below, upon entering the loop, PowerShell starts to execute the cmdlets in the script block until it runs the break keyword. At this point, PowerShell escapes the loop and runs the rest of the commands in the script.

We may also specify on which conditions PowerShell will exit the loop. For example, let’s assume we would like to break the loop when the value of our variable becomes three. In this case, we’ll use an if statement to check the condition and escape the loop once our condition is met.

Write-Host Script Start
$NumberList = 1..5
foreach ($number in $NumberList) {
    Write-Host The current number is $number
    if ($number -eq 3) {
        break
    }
}
Write-Host Commands after the loop
Write-Host Script End 
We used an if statement to specify on which conditions PowerShell will exit the loop

As we previously explained, if we have a nested loop, the break keyword will only escape the loop that is being called, which won’t affect the parent loop.

$NumberList = 1..5
$CharList = "A", "B", "C", "D", "E" 
foreach ($number in $NumberList) {
    Write-Host The current number is: $number
    foreach ($character in $CharList) {
        Write-Host The current character is: $character
        break
    }
} 
In a nested loop, the break keyword will only escape the loop that is being called

You can see here that the nested loop is breaking out on its first iteration, while the outer loops completed all of their cycles.

How to use the PowerShell return keyword

Using the return keyword in PowerShell will allow you to return to the previous call point without closing your current console. Using this keyword will exit a function, script, or script block at a specific point, return a value, or indicate the end of the scope.

If you run the return command from the console, it will just return the value instead of closing it. If you run it from a script, it will return the value, exit the script, and the rest of the commands will not be executed:

Write-Host Script Start
Write-Host Executing return command
return "HelloWorld"
Write-Host Script End 

In this example, you see that the execution of the script is stopped after the return keyword and that the cmdlet that follows it is not being executed.

Summary

In this article, we have reviewed the different ways to terminate PowerShell sessions, scripts, loops, and switch cases. Each method leverages a specific keyword and has its own use case. If you learn how to use the exit command and the break and return keywords properly, you will get better control over how your scripts run.

Article saved!

Access saved content from your profile page. View Saved