ps1exec

Copyright © 2009-2018 by Bill Stewart

Freeware License

This program may be used freely in any environment without payment to the author, with the following conditions:

• Give me credit.
• Let me know how you're using the program.
• The program and this documentation must not be modified.
• The program cannot be used as a part another software package without notifying the author.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the IMPLIED WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Introduction

I wrote this program to address the following challenges of running PowerShell scripts from outside the PowerShell command line:

• Execution policy. If an execution policy is not defined, we always have to specify -ExecutionPolicy Bypass.
• Window state. Since powershell.exe is itself a console program, we can't control its initial console window state. (The powershell.exe -WindowStyle parameter only sets the console window state after it initially appears at its default position.)
• Elevation. Other than the Task Scheduler, there's not a simple and straightforward way to run a PowerShell script elevated.
• Keep console window open when complete. This is a commonly requested feature, as some users want to see the output in the PowerShell console window before it closes.

ps1exec addresses these by doing the following:

• It uses -ExecutionPolicy Bypass on the powershell.exe command line so the script will run regardless of the execution policy.
• It can set the initial window state for the powershell.exe console window (for example, hidden).
• It can request elevation for the powershell.exe process that runs the script.
• It can run a script and pause the output window (to give you a chance to view script output before the window closes).

ps1exec requires at least PowerShell version 2. (PowerShell version 2 is included with Windows 7/Server 2008 R2. Later OS versions include newer PowerShell versions.)

ps1exec is provided in 32-bit (x86) and 64-bit (x64) versions. If you have a 64-bit version of Windows, the 32-bit version of ps1exec.exe works also, but be aware it runs the 32-bit version of powershell.exe.

Usage

ps1exec's command-line syntax is as follows:

ps1exec [-s n] [-d "path"] [-e] [-w] [-q] [-t "title"] [-k] [-n] [-p] [-m] "scriptfile" [-- ...]

The parameters are as follows:

-s n

n is a number that specifies the default initial window state for the PowerShell console window. The default window state is 1. See the section Window States for the -s Parameter for possible values for the -s parameter.

-d "path"

Specify a starting directory for powershell.exe. If the path contains spaces, enclose it in quotes ("). This parameter is ignored if you specify -e. (See the section Elevation Notes for more information.)

-e

Request elevation before running the script (i.e., "Run as administrator"). See the section Elevation Notes for more information.

-w

Waits for powershell.exe to close. Without -w, ps1exec will start powershell.exe to run the script and then exit immediately. (For example, you can use -w if you use ps1exec to schedule a PowerShell script so that the scheduler will know when the script finishes.) If you use this parameter, ps1exec will return the powershell.exe exit code once it completes.

-q

Runs ps1exec quietly (no error dialogs). Without -q, ps1exec will display a dialog box if it encounters an error. This parameter is recommended if you use ps1exec to schedule scripts.

-t "title"

Specifies a console window title.^* If the title contains spaces, enclose it in quotes ("). Implies -w.

-k

Keeps the console window open after the script completes.^* Implies -w.

-n

Runs the script non-interactively (i.e., it adds the -NonInteractive parameter to the powershell.exe command line).

-p

Loads the PowerShell profile before running the script (that is, this parameter causes ps1exec to omit the -NoProfile parameter from the powershell.exe command line).

-m

Runs powershell.exe in multi-threaded apartment mode (i.e., it adds the -Mta parameter to the powershell.exe command line).

"scriptfile"

Specify the filename of the PowerShell script (.ps1) file you want to run. If the script's path and/or filename contains spaces, enclose the entire path and filename in quotes (").

--

If the script requires parameters, put them at the end of the command line following two hyphens (--).

^*See the section Temporary Script Generation for more details about the -t and -k parameters.

Window States for the -s Parameter

The following table documents applicable values for the -s parameter:

(There are other window state values, but they aren't used for setting the initial window state so they are omitted from the above table.)

Elevation Notes

The -e parameter requests elevation for the PowerShell script. It is a shortcut for the following manual steps:

1. Right-click the PowerShell icon and choose Run as administrator.
2. Enter the script's name at the PowerShell prompt to run it.

The -e parameter only provokes the elevation prompt; it cannot automatically enter credentials or bypass the elevation prompt.

If the current process is already elevated, the -e parameter does nothing.

Notes:

• Windows automatically sets the starting directory for an elevated process to the System32 directory (e.g., C:\Windows\System32). This is by design for security reasons. This means that, when you use -e,
  • ps1exec ignores the -d parameter, and
  • ps1exec won't be able to find your script unless you specify its full path and filename.
• Do not use -e when scheduling a script for unattended use because there's no one to answer the credential prompt (i.e., ps1exec will simply hang indefinitely).

Temporary Script Generation

If you use the -t or -k parameters, ps1exec creates a temporary PowerShell script file in the Temp directory. The content of the temporary script file is as follows:

$Host.UI.RawUI.WindowTitle = 'title'
& 'scriptfile' [parameters]
Read-Host 'Press ENTER to continue'
exit $LASTEXITCODE

Notes:

• ps1exec adds the first line if the -t parameter is specified, and title is the window title specified with the -t parameter.
• scriptfile is the file name of the script specified on ps1exec's command line.
• parameters are the script's parameters, if any.
• ps1exec adds the Read-Host cmdlet to the temporary script if -k was specified.
• The last line of the temporary script ensures that powershell.exe terminates with the correct exit code.

ps1exec executes the temporary script file using powershell.exe's -File parameter (see the Technical Details section). After powershell.exe terminates, ps1exec automatically deletes the temporary script file.

ps1exec assumes the -w parameter if you specify -t and/or -k.

Examples

Here are some examples of how you might use ps1exec (the script names are made up):

Run a script:

ps1exec "C:\Program Files\PowerShell Scripts\Test Script.ps1"

Run a script with parameters:

ps1exec C:\bin\scripts\Cleanup.ps1 -- -Days 30

Run the script hidden and specify Ken O'Dell as the argument for the script's -Name parameter:

ps1exec -s 0 C:\bin\scripts\Add-User.ps1 -- -Name "Ken O'Dell"

Run a script with D:\Program Files as the argument for the script's -Path parameter:

ps1exec "C:\Script Files\Get-Items.ps1" -- -Path "D:\Program Files"

Run a script elevated and minimized:

ps1exec -e -s 7 "C:\Program Files\Scripts\Cleanup.ps1"

Technical Details

ps1exec detects the location of powershell.exe by reading the following registry value:

Hive: HKEY_LOCAL_MACHINE
Subkey: SOFTWARE\Microsoft\PowerShell\1\ShellIds\Microsoft.PowerShell
Value: Path

ps1exec constructs the PowerShell command line as follows:

path\powershell.exe [-NoProfile] [-NonInteractive] [-Mta] -ExecutionPolicy Bypass -File "script" [parameters]

Notes:

• path\powershell.exe is the path and filename of powershell.exe as read from the registry.
• The -NoProfile, -NonInteractive, and -Mta parameters are added or omitted based on the -p, -n, and -m parameters.
• script is the script file name on ps1exec's command line if the -t and/or -k parameters are not used; otherwise, it is the temporary script file's name (see the section Temporary Script Generation for details).
• parameters are the script's parameters, if -t and/or -k are not used. (If -t and/or -k are used, ps1exec puts the script's parameters in the temporary script file rather than on the powershell.exe command line.)

Once it has constructed the command line (and created the temporary script file, if necessary), it executes powershell.exe using the ShellExecuteEx Windows API. If elevation was requested (-e), ps1exec uses the runas verb; otherwise, it uses the open verb.

If -t, -k, and/or -w are used, ps1exec waits for the powershell.exe process to terminate. Once powershell.exe terminates, ps1exec exits with powershell.exe's exit code.

Version History

2.0 (21 May 2018)

• At least PowerShell v2.0 required.
• Use powershell.exe -File and -ExecutionPolicy parameters.
• Use ShellExecuteEx API so we can request elevation.
• Use temporary script file if -t and/or -k.

1.0 (8 July 2009)

• Initial version.