< Back
Invoke-CPowerShell
Post
NAME Invoke-CPowerShell
SYNOPSIS
Invokes a script block, script, command, or encoded command under a new `powershell.exe` process.
SYNTAX
Invoke-CPowerShell -ScriptBlock <ScriptBlock> [-ArgumentList <Object[]>] [-OutputFormat <String>]
[-ExecutionPolicy {Unrestricted | RemoteSigned | AllSigned | Restricted | Default | Bypass | Undefined}]
[-NonInteractive] [-x86] [-Runtime <String>] [<CommonParameters>]
Invoke-CPowerShell -Command <Object> [-ArgumentList <Object[]>] [-Encode] [-OutputFormat <String>]
[-ExecutionPolicy {Unrestricted | RemoteSigned | AllSigned | Restricted | Default | Bypass | Undefined}]
[-NonInteractive] [-x86] [-Runtime <String>] [-Credential <PSCredential>] [<CommonParameters>]
Invoke-CPowerShell -FilePath <String> [-ArgumentList <Object[]>] [-OutputFormat <String>] [-ExecutionPolicy
{Unrestricted | RemoteSigned | AllSigned | Restricted | Default | Bypass | Undefined}] [-NonInteractive] [-x86]
[-Runtime <String>] [-Credential <PSCredential>] [<CommonParameters>]
DESCRIPTION
The `Invoke-CPowerShell` 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-CPowerShell` 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-CPowerShell` 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-CPowerShell` uses a temporary [activation configuration
file](https://msdn.microsoft.com/en-us/librar ... .100).aspx) 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
-ScriptBlock <ScriptBlock>
The script block to pass to `powershell.exe`.
Required? true
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? 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-CPowerShell` 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-CPowerShell` will run the script block as a script block. In the next major version of Carbon, this
parameter will stop accepting `ScriptBlock` objects.
Required? true
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-FilePath <String>
The script to run.
Required? true
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? 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.
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? 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.
Required? false
Position? named
Default value False
Accept pipeline input? false
Accept wildcard characters? 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.
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-ExecutionPolicy
The execution policy to use when running `powershell.exe`. Passed to `powershell.exe` with its
`-ExecutionPolicy` parameter.
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-NonInteractive [<SwitchParameter>]
Run `powershell.exe` non-interactively. This passes the `-NonInteractive` switch to powershell.exe.
Required? false
Position? named
Default value False
Accept pipeline input? false
Accept wildcard characters? 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`.
Required? false
Position? named
Default value False
Accept pipeline input? false
Accept wildcard characters? 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.
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? 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.
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
<CommonParameters>
This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
OutBuffer, PipelineVariable, and OutVariable. For more information, see
about_CommonParameters (https:/go.microsoft.com/fwlink/?LinkID=113216).
INPUTS
OUTPUTS
-------------------------- EXAMPLE 1 --------------------------
PS C:\\>Invoke-CPowerShell -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 --------------------------
PS C:\\>Invoke-CPowerShell -ScriptBlock { $PSVersionTable } -x86
Runs a 32-bit PowerShell process, return the $PSVersionTable from that process.
-------------------------- EXAMPLE 3 --------------------------
PS C:\\>Invoke-CPowerShell -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 --------------------------
PS C:\\>Invoke-CPowerShell -FilePath C:\\Projects\\Carbon\\bin\\Set-CDotNetConnectionString.ps1 -ArgumentList
'-Name','myConn','-Value',"'data source=.\\DevDB;Integrated Security=SSPI;'"
Runs the `Set-CDotNetConnectionString.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 --------------------------
PS C:\\>Invoke-CPowerShell -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 --------------------------
PS C:\\>Invoke-CPowerShell -FilePath Get-PsVersionTable.ps1 -Credential $cred
Demonstrates that you can run PowerShell scripts as a specific user with the `Credential` parameter.
-------------------------- EXAMPLE 7 --------------------------
PS C:\\>Invoke-CPowerShell -FilePath Get-PsVersionTable.ps1 -Credential $cred
Demonstrates that you can run PowerShell scripts as a specific user with the `Credential` parameter.
-------------------------- EXAMPLE 8 --------------------------
PS C:\\>Invoke-CPowerShell -Command '$PSVersionTable'
Demonstrates how to run a PowerShell command contained in a string. You are responsible for quoting things
correctly.
-------------------------- EXAMPLE 9 --------------------------
PS C:\\>Invoke-CPowerShell -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-CPowerShell` does the base-64 encoding for you.
-------------------------- EXAMPLE 10 --------------------------
PS C:\\>Invoke-CPowerShell -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.
RELATED LINKS
SYNOPSIS
Invokes a script block, script, command, or encoded command under a new `powershell.exe` process.
SYNTAX
Invoke-CPowerShell -ScriptBlock <ScriptBlock> [-ArgumentList <Object[]>] [-OutputFormat <String>]
[-ExecutionPolicy {Unrestricted | RemoteSigned | AllSigned | Restricted | Default | Bypass | Undefined}]
[-NonInteractive] [-x86] [-Runtime <String>] [<CommonParameters>]
Invoke-CPowerShell -Command <Object> [-ArgumentList <Object[]>] [-Encode] [-OutputFormat <String>]
[-ExecutionPolicy {Unrestricted | RemoteSigned | AllSigned | Restricted | Default | Bypass | Undefined}]
[-NonInteractive] [-x86] [-Runtime <String>] [-Credential <PSCredential>] [<CommonParameters>]
Invoke-CPowerShell -FilePath <String> [-ArgumentList <Object[]>] [-OutputFormat <String>] [-ExecutionPolicy
{Unrestricted | RemoteSigned | AllSigned | Restricted | Default | Bypass | Undefined}] [-NonInteractive] [-x86]
[-Runtime <String>] [-Credential <PSCredential>] [<CommonParameters>]
DESCRIPTION
The `Invoke-CPowerShell` 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-CPowerShell` 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-CPowerShell` 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-CPowerShell` uses a temporary [activation configuration
file](https://msdn.microsoft.com/en-us/librar ... .100).aspx) 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
-ScriptBlock <ScriptBlock>
The script block to pass to `powershell.exe`.
Required? true
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? 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-CPowerShell` 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-CPowerShell` will run the script block as a script block. In the next major version of Carbon, this
parameter will stop accepting `ScriptBlock` objects.
Required? true
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-FilePath <String>
The script to run.
Required? true
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? 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.
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? 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.
Required? false
Position? named
Default value False
Accept pipeline input? false
Accept wildcard characters? 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.
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-ExecutionPolicy
The execution policy to use when running `powershell.exe`. Passed to `powershell.exe` with its
`-ExecutionPolicy` parameter.
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-NonInteractive [<SwitchParameter>]
Run `powershell.exe` non-interactively. This passes the `-NonInteractive` switch to powershell.exe.
Required? false
Position? named
Default value False
Accept pipeline input? false
Accept wildcard characters? 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`.
Required? false
Position? named
Default value False
Accept pipeline input? false
Accept wildcard characters? 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.
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? 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.
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
<CommonParameters>
This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
OutBuffer, PipelineVariable, and OutVariable. For more information, see
about_CommonParameters (https:/go.microsoft.com/fwlink/?LinkID=113216).
INPUTS
OUTPUTS
-------------------------- EXAMPLE 1 --------------------------
PS C:\\>Invoke-CPowerShell -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 --------------------------
PS C:\\>Invoke-CPowerShell -ScriptBlock { $PSVersionTable } -x86
Runs a 32-bit PowerShell process, return the $PSVersionTable from that process.
-------------------------- EXAMPLE 3 --------------------------
PS C:\\>Invoke-CPowerShell -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 --------------------------
PS C:\\>Invoke-CPowerShell -FilePath C:\\Projects\\Carbon\\bin\\Set-CDotNetConnectionString.ps1 -ArgumentList
'-Name','myConn','-Value',"'data source=.\\DevDB;Integrated Security=SSPI;'"
Runs the `Set-CDotNetConnectionString.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 --------------------------
PS C:\\>Invoke-CPowerShell -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 --------------------------
PS C:\\>Invoke-CPowerShell -FilePath Get-PsVersionTable.ps1 -Credential $cred
Demonstrates that you can run PowerShell scripts as a specific user with the `Credential` parameter.
-------------------------- EXAMPLE 7 --------------------------
PS C:\\>Invoke-CPowerShell -FilePath Get-PsVersionTable.ps1 -Credential $cred
Demonstrates that you can run PowerShell scripts as a specific user with the `Credential` parameter.
-------------------------- EXAMPLE 8 --------------------------
PS C:\\>Invoke-CPowerShell -Command '$PSVersionTable'
Demonstrates how to run a PowerShell command contained in a string. You are responsible for quoting things
correctly.
-------------------------- EXAMPLE 9 --------------------------
PS C:\\>Invoke-CPowerShell -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-CPowerShell` does the base-64 encoding for you.
-------------------------- EXAMPLE 10 --------------------------
PS C:\\>Invoke-CPowerShell -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.
RELATED LINKS