Invoke-PowerShell

Invokes a script block, script, command, or encoded command under a new powershell.exe process.

Syntax

Invoke-PowerShell -ScriptBlock <ScriptBlock> [-ArgumentList <Object[]>] [-OutputFormat <String>] [-ExecutionPolicy {Unrestricted | RemoteSigned | AllSigned | Restricted | Default | Bypass | Undefined}] [-NonInteractive] [-x86] [-Runtime <String>] [<CommonParameters>]
Invoke-PowerShell -Command <Object> [-ArgumentList <Object[]>] [-Encode] [-OutputFormat <String>] [-ExecutionPolicy {Unrestricted | RemoteSigned | AllSigned | Restricted | Default | Bypass | Undefined}] [-NonInteractive] [-x86] [-Runtime <String>] [-Credential <PSCredential>] [<CommonParameters>]
Invoke-PowerShell -FilePath <String> [-ArgumentList <Object[]>] [-OutputFormat <String>] [-ExecutionPolicy {Unrestricted | RemoteSigned | AllSigned | Restricted | Default | Bypass | Undefined}] [-NonInteractive] [-x86] [-Runtime <String>] [-Credential <PSCredential>] [<CommonParameters>]

Description

The Invoke-PowerShell scripts executes powershell.exe. All processes are started with powershell.exe's -NoProfile paramter. You can specify values for powershell.exe's OutputFormat, ExecutionPolicy, and NonInteractive paramters via parameters of the same name on the Invoke-PowerShell function. Use the Runtime parameter to run powershell.exe version 2.

To run a script, pass the path to the script with the -FilePath paramter. Pass any script arguments with the ArgumentList parameter. You must escape any parameters. They are passed to powershell.exe as-is.

To run a script block, pass the script block with the -ScriptBlock parameter. Pass any script block arguments with the ArgumentList parameter. You must escape any parameters. They are passed to powershell.exe as-is.

To run a command (Carbon 2.3.0 and later only), pass the command (i.e. string of PowerShell code) with the Command parameter. Any arguments to your command must be in the command itself. You must do any escaping.

To run an encoded command (Carbon 2.3.0 and later only), pass the command (i.e. string of PowerShell code) with the Command parameter and the -Encode switch. Invoke-PowerShell will base-64 encode your command for you and pass it to powershell.exe with its -EncodedCommand parameter.

Beginning in Carbon 2.3.0, you can run scripts, commands, and encoded commands as another user. Pass that user's credentials with the Credential parameter.

On 64-bit operating systems, use the -x86 switch to run the new powershell.exe process under 32-bit PowerShell. If this switch is ommitted, powershell.exe will be run under a 64-bit PowerShell process (even if called from a 32-bit process). On 32-bit operating systems, this switch is ignored.

The Runtime paramter controls what version of the .NET framework powershell.exe should use. Pass v2.0 and v4.0 to run under .NET versions 2.0 or 4.0, respectivey. Those frameworks must be installed. When running under PowerShell 2, Invoke-PowerShell uses a temporary activation configuration file to force PowerShell 2 to use .NET 4. When run under PowerShell 3 and later, powershell.exe is run with the -Version switch set to 2.0 to run powershell.exe under .NET 2.

If using PowerShell v3.0 or later with a version of Carbon before 2.0, you can only run script blocks under a v4.0 CLR. PowerShell converts script blocks to an encoded command, and when running encoded commands, PowerShell doesn't allow the -Version parameter for running PowerShell under a different version. To run code under a .NET 2.0 CLR from PowerShell 3, use the FilePath parameter to run a specfic script.

Parameters

Name Type Description Required? Pipeline Input Default Value
ScriptBlock ScriptBlock

The script block to pass to powershell.exe.

true false
Command Object

The command to run, as a string. Passed to PowerShell.exe as the value to the -Command parameter.

Use the -Encode switch to avoid complicated quoting, and have Invoke-PowerShell encode this command for you and pass it to powershell.exe's `-EncodedCommand parameter.

This parameter was introduced in Carbon 2.3.0. In previous versions, this parameter was an alias to the ScriptBlock parameter. To maintain backwards-compatibility, if you pass a ScriptBlock to this parameter, Invoke-PowerShell will run the script block as a script block. In the next major version of Carbon, this parameter will stop accepting ScriptBlock objects.

true false
FilePath String

The script to run.

true false
ArgumentList Object[]

Any arguments to pass to the script or command. These are not powershell.exe arguments. They are passed to powershell.exe as-is, so you'll need to escape them.

false false
Encode SwitchParameter

Base-64 encode the command in Command and run it with powershell.exe's -EncodedCommand switch.

This parameter was added in Carbon 2.3.0.

false false False
OutputFormat String

Determines how output from the PowerShel command is formatted. The value of this parameter is passed as-is to powershell.exe with its -OutputFormat paramter.

false false
ExecutionPolicy ExecutionPolicy

The execution policy to use when running powershell.exe. Passed to powershell.exe with its -ExecutionPolicy parameter.

false false
NonInteractive SwitchParameter

Run powershell.exe non-interactively. This passes the -NonInteractive switch to powershell.exe.

false false False
x86 SwitchParameter

Run the x86 (32-bit) version of PowerShell. if not provided, the version which matches the OS architecture is used, regardless of the architecture of the currently running process. I.e. this command is run under a 32-bit PowerShell on a 64-bit operating system, without this switch, Invoke-Command will start a 64-bit powershell.exe.

false false False
Runtime String

The CLR to use. Must be one of v2.0 or v4.0. Default is the current PowerShell runtime.

Beginning with Carbon 2.3.0, this parameter is ignored, since Carbon 2.0 and later only supports PowerShell 4 and you can't run PowerShell 4 under .NET 2.0.

This parameter is OBSOLETE and will be removed in a future major version of Carbon.

false false
Credential PSCredential

Run powershell.exe as a specific user. Pass that user's credentials with this parameter.

This parameter is new in Carbon 2.3.0.

false false

EXAMPLE 1

Invoke-PowerShell -ScriptBlock { $PSVersionTable }

Runs a separate PowerShell process which matches the architecture of the operating system, returning the $PSVersionTable from that process. This will fail under 32-bit PowerShell on a 64-bit operating system.

EXAMPLE 2

Invoke-PowerShell -ScriptBlock { $PSVersionTable } -x86

Runs a 32-bit PowerShell process, return the $PSVersionTable from that process.

EXAMPLE 3

Invoke-PowerShell -ScriptBlock { $PSVersionTable } -Runtime v4.0

Runs a separate PowerShell process under the v4.0 .NET CLR, returning the $PSVersionTable from that process. Should return a CLRVersion of 4.0.

EXAMPLE 4

Invoke-PowerShell -FilePath C:\Projects\Carbon\bin\Set-DotNetConnectionString.ps1 -ArgumentList '-Name','myConn','-Value',"'data source=.\DevDB;Integrated Security=SSPI;'"

Runs the Set-DotNetConnectionString.ps1 script with ArgumentList as arguments/parameters.

Note that you have to double-quote any arguments with spaces. Otherwise, the argument gets interpreted as multiple arguments.

EXAMPLE 5

Invoke-PowerShell -FilePath Get-PsVersionTable.ps1 -x86 -ExecutionPolicy RemoteSigned

Shows how to run powershell.exe with a custom executin policy, in case the running of scripts is disabled.

EXAMPLE 6

Invoke-PowerShell -FilePath Get-PsVersionTable.ps1 -Credential $cred

Demonstrates that you can run PowerShell scripts as a specific user with the Credential parameter.

EXAMPLE 7

Invoke-PowerShell -FilePath Get-PsVersionTable.ps1 -Credential $cred

Demonstrates that you can run PowerShell scripts as a specific user with the Credential parameter.

EXAMPLE 8

Invoke-PowerShell -Command '$PSVersionTable'

Demonstrates how to run a PowerShell command contained in a string. You are responsible for quoting things correctly.

EXAMPLE 9

Invoke-PowerShell -Command '$PSVersionTable' -Encode

Demonstrates how to run a base-64 encode then run PowerShell command contained in a string. This runs the command using PowerShell's -EncodedCommand parameter. Invoke-PowerShell does the base-64 encoding for you.

EXAMPLE 10

Invoke-PowerShell -Command '$env:USERNAME' -Credential $credential

Demonstrates how to run a PowerShell command as another user. Uses Start-Process to launch powershell.exe as the user.