Returning an exit code from a PowerShell script

Tuesday, July 13, 2010

Returning an exit code from a PowerShell script seems easy… but it isn’t that obvious. In this blog post I will show you an approach that works for PowerShell scripts that can be called from both PowerShell and batch scripts, where the command to be executed can be specified in a string, execute in its own context and always return the correct error code.

Below is a kind of transcript of the steps that I took to get to an approach that works for me. It is a transcript of the steps I took, for the conclusions just jump to the end.

In many blog posts you can read about calling a PowerShell script that you call from a batch script, and how to return an error code. This comes down to the following:

c:\temp\exit.ps1:

Write-Host "Exiting with code 12345"
exit 12345

c:\temp\testexit.cmd:

@PowerShell -NonInteractive -NoProfile -Command "& {c:\temp\exit.ps1; exit $LastExitCode }"
@echo From Cmd.exe: Exit.ps1 exited with exit code %errorlevel%

Executing c:\temp\testexit.cmd results in the following output:

Exiting with code 12345
From Cmd.exe: Exit.ps1 exited with exit code 12345

But now we want to call it from another PowerShell script, by executing PowerShell:

c:\temp\testexit.ps1:

PowerShell -NonInteractive -NoProfile -Command c:\temp\exit.ps1
Write-Host "From PowerShell: Exit.ps1 exited with exit code $LastExitCode"

Executing c:\temp\testexit.ps1 results in the following output:

Exiting with code 12345
From PowerShell: Exit.ps1 exited with exit code 1

This is not what we expected… What happs? If the script just returns the exit code is 0, otherwise the exit code is 1, even if you exit with an exit code!?

But what if we call the script directly, instead of through the PowerShell command?

We change exit.ps1 to:

Write-Host "Global variable value: $globalvariable"
Write-Host "Exiting with code 12345"
exit 12345

And we change testexit.ps1 to:

$global:globalvariable = "My global variable value"
& c:\temp\exit.ps1
Write-Host "From PowerShell: Exit.ps1 exited with exit code $LastExitCode"

Executing c:\temp\testexit.ps1 results in the following output:

Global variable value: My global variable value
Exiting with code 12345
From PowerShell: Exit.ps1 exited with exit code 12345

This is what we wanted! But now we are executing the script exit.ps1 in the context of the testexit.ps1 script, the globally defined variable $globalvariable is still known. This is not what we want. We want to execute it is isolation.

We change c:\temp\testexit.ps1 to:

$global:globalvariable = "My global variable value"
PowerShell -NonInteractive -NoProfile -Command c:\temp\exit.ps1
Write-Host "From PowerShell: Exit.ps1 exited with exit code $LastExitCode"

Executing c:\temp\testexit.ps1 results in the following output:

Global variable value:
Exiting with code 12345
From PowerShell: Exit.ps1 exited with exit code 1

We are not executing exit.ps1 in the context of testexit.ps1, which is good. But how can we reach the holy grail:

Write a PowerShell script that can be executed from batch scripts an from PowerShell
That return a specific error code
That can specified as a string
Can be executed both in the context of a calling PowerShell script AND (through a call to PowerShell) in it’s own execution space

We change c:\temp\testexit.ps1 to:

$global:globalvariable = "My global variable value"
PowerShell -NonInteractive -NoProfile -Command { c:\temp\exit.ps1 ; exit $LastExitCode }
Write-Host "From PowerShell: Exit.ps1 exited with exit code $LastExitCode"

This is the same approach as when we called it from the batch script. Executing c:\temp\testexit.ps1 results in the following output:

Global variable value:
Exiting with code 12345
From PowerShell: Exit.ps1 exited with exit code 12345

This is close. But we want to be able to specify the command to be executed as string, for example:

$command = "c:\temp\exit.ps1 -param1 x -param2 y"

We change c:\temp\exit.ps1 to: (support for variables, test if in its own context)

param( $param1, $param2)
Write-Host "param1=$param1; param2=$param2"
Write-Host "Global variable value: $globalvariable"
Write-Host "Exiting with code 12345"
exit 12345

If we change c:\temp\testexit.ps1 to:

$global:globalvariable = "My global variable value"
$command = "c:\temp\exit.ps1 -param1 x -param2 y"
Invoke-Expression -Command $command
Write-Host "From PowerShell: Exit.ps1 exited with exit code $LastExitCode"

We get a good exit code, but we are still executing in the context of testexit.ps1.

If we use the same trick as in calling from a batch script, that worked before?

We change c:\temp\testexit.ps1 to:

$global:globalvariable = "My global variable value"
$command = "c:\temp\exit.ps1 -param1 x -param2 y"
PowerShell -NonInteractive -NoProfile -Command { $command; exit $LastErrorLevel }
Write-Host "From PowerShell: Exit.ps1 exited with exit code $LastExitCode"

Executing c:\temp\testexit.ps1 results in the following output:

From PowerShell: Exit.ps1 exited with exit code 0

Ok, lets use the Invoke-Expression again. We change c:\temp\testexit.ps1 to:

$global:globalvariable = "My global variable value"
$command = "c:\temp\exit.ps1 -param1 x -param2 y"
PowerShell -NonInteractive -NoProfile -Command { Invoke-Expression -Command $command; exit $LastErrorLevel }
Write-Host "From PowerShell: Exit.ps1 exited with exit code $LastExitCode"

Executing c:\temp\testexit.ps1 results in the following output:

Cannot bind argument to parameter 'Command' because it is null.
At :line:3 char:10
+ PowerShell <<<< -NonInteractive -NoProfile -Command { Invoke-Expression -Command $command; exit $LastErrorLevel }

From PowerShell: Exit.ps1 exited with exit code 1

We should go back to executing the command as a string, so not within brackets (in a script block). We change c:\temp\testexit.ps1 to:

$global:globalvariable = "My global variable value"
$command = "c:\temp\exit.ps1 -param1 x -param2 y"
PowerShell -NonInteractive -NoProfile -Command $command
Write-Host "From PowerShell: Exit.ps1 exited with exit code $LastExitCode"

Executing c:\temp\testexit.ps1 results in the following output:

param1=x; param2=y
Global variable value:
Exiting with code 12345
From PowerShell: Exit.ps1 exited with exit code 1

Ok, we can execute the specified command text as if it is a PowerShell command. But we still have the exit code problem, only 0 or 1 is returned.

Lets try something completely different. We change c:\temp\exit.ps1 to:

param( $param1, $param2)

function ExitWithCode
{
    param
    (
        $exitcode
    )

    $host.SetShouldExit($exitcode)
    exit
}

Write-Host "param1=$param1; param2=$param2"
Write-Host "Global variable value: $globalvariable"
Write-Host "Exiting with code 12345"
ExitWithCode -exitcode 12345
Write-Host "After exit"

What we do is specify to the host the exit code we would like to use, and then just exit, all in the simplest utility function.

Executing c:\temp\testexit.ps1 results in the following output:

param1=x; param2=y
Global variable value:
Exiting with code 12345
From PowerShell: Exit.ps1 exited with exit code 12345

Ok, this fulfills all our holy grail dreams! But couldn’t we make the call from the batch script also simpler?

Change c:\temp\testexit.cmd to:

@PowerShell -NonInteractive -NoProfile -Command "c:\temp\exit.ps1 -param1 x -param2 y"
@echo From Cmd.exe: Exit.ps1 exited with exit code %errorlevel%

Executing c:\temp\testexit.cmd results in the following output:

param1=x; param2=y
Global variable value:
Exiting with code 12345
From Cmd.exe: Exit.ps1 exited with exit code 12345

This is even simpler! We can now just call the PowerShell code, without the exit $LastExitCode trick!

========================= CONCLUSIONS ============================

And now the conclusions after this long long story, that took a lot of time to find out (and to read for you):

Don’t use exit to return a value from PowerShell code, but use the following function:

function ExitWithCode
{
    param
    (
        $exitcode
    )

$host.SetShouldExit($exitcode)
exit
}

Call script from batch using:

PowerShell -NonInteractive -NoProfile -Command "c:\temp\exit.ps1 -param1 x -param2 y"

echo %errorlevel%

Call from PowerShell with: (Command specified in string, execute in own context)
$command = "c:\temp\exit.ps1 -param1 x -param2 y"
PowerShell -NonInteractive -NoProfile -Command $command

$LastExitCode contains the exit code
Call from PowerShell with: (Direct command, execute in own context)

PowerShell -NonInteractive -NoProfile -Command { c:\temp\exit.ps1 -param1 x -param2 y }

$LastExitCode contains the exit code

Call from Powershell with: (Command specified in string, invoke in caller context)

$command = "c:\temp\exit.ps1 -param1 x -param2 y"
Invoke-Expression -Command $command

$LastExitCode contains the exit code

Call from PowerShell with: (Direct command, execute in caller context)

& c:\temp\exit.ps1 -param1 x -param2 y

$LastExitCode contains the exit code

Nice post, but why haven't you used the file switch instead of the command switch? If you just want to execute a script and are interested in its exit code this seems to me much simpler:

powershell -noprofile -noninteractive -file C:\temp\exit.ps1

Peter M. - Tuesday, September 28, 2010 6:38:29 PM

With -file you can't specify any arguments..

Serge van den Oever [Macaw] - Thursday, June 23, 2011 3:42:49 PM

Actually, you can specify arguments, at least in v2 PowerShell.

powershell -File myscript.ps1 -param1 value1 -param2 value2 , etc..

this is working fine for me.

Jesse Wolfe - Saturday, August 13, 2011 12:20:30 AM

Thanks for sharing. In function ExitWithCode, don't you want to "exit $exitcode"?

Brad Williams - Tuesday, November 22, 2011 5:19:29 PM

That not work for me (XP/PS1), in batch execute my exit code is 0, never mind what I set in the ps script.

Panayot - Sunday, October 21, 2012 4:23:03 AM

In other words, whatever is value of $exitcode to put in $host.SetShouldExit($exitcode), %errorlevel% return 0 or what I specify for exit command, so "exit 358" works and give to me exit code 358.

Panayot - Sunday, October 21, 2012 4:33:15 AM

Amazing post. Quick question: Shouldn't one of the explanations in the Conclusion for how to call it include the '&' character for -Command?

static - Thursday, December 6, 2012 6:00:58 PM

Highly descriptive post, I loved that bit. Will there be
a part 2?

Mccann - Wednesday, March 20, 2013 9:48:01 AM

Hey there! I just wish to offer you a big thumbs up for your excellent info you've got right here on this post. I will be returning to your site for more soon.

Rupp - Wednesday, March 20, 2013 11:23:42 AM

9 Comments