Invokes a script block, script, command, or encoded command under a new powershell.exe process.
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>]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.
| Name | Type | Description | Required? | Pipeline Input | Default Value |
|---|---|---|---|---|---|
| ScriptBlock | ScriptBlock | The script block to pass to |
true | false | |
| Command | Object | The command to run, as a string. Passed to PowerShell.exe as the value to the Use the This parameter was introduced in Carbon 2.3.0. In previous versions, this parameter was an alias to the |
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 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 |
false | false | |
| ExecutionPolicy | ExecutionPolicy | The execution policy to use when running |
false | false | |
| NonInteractive | SwitchParameter | Run |
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, |
false | false | False |
| Runtime | String | The CLR to use. Must be one of 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 This parameter is new in Carbon 2.3.0. |
false | false |
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.
Invoke-PowerShell -ScriptBlock { $PSVersionTable } -x86Runs a 32-bit PowerShell process, return the $PSVersionTable from that process.
Invoke-PowerShell -ScriptBlock { $PSVersionTable } -Runtime v4.0Runs a separate PowerShell process under the v4.0 .NET CLR, returning the $PSVersionTable from that process. Should return a CLRVersion of 4.0.
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.
Invoke-PowerShell -FilePath Get-PsVersionTable.ps1 -x86 -ExecutionPolicy RemoteSignedShows how to run powershell.exe with a custom executin policy, in case the running of scripts is disabled.
Invoke-PowerShell -FilePath Get-PsVersionTable.ps1 -Credential $credDemonstrates that you can run PowerShell scripts as a specific user with the Credential parameter.
Invoke-PowerShell -FilePath Get-PsVersionTable.ps1 -Credential $credDemonstrates that you can run PowerShell scripts as a specific user with the Credential parameter.
Invoke-PowerShell -Command '$PSVersionTable'Demonstrates how to run a PowerShell command contained in a string. You are responsible for quoting things correctly.
Invoke-PowerShell -Command '$PSVersionTable' -EncodeDemonstrates 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.
Invoke-PowerShell -Command '$env:USERNAME' -Credential $credentialDemonstrates how to run a PowerShell command as another user. Uses Start-Process to launch powershell.exe as the user.