A Comprehensive Guide to Passing Named Parameters with Invoke-Command in PowerShell

In remote script execution with PowerShell, Invoke-Command is a core cmdlet that enables running commands or scripts on remote computers. However, when scripts include named parameters, especially switch parameters, passing these can pose syntactic and semantic challenges. This article, based on a typical technical Q&A scenario, details how to correctly pass such parameters.

Problem Context and Core Challenges

A user has a script ArchiveEventLogs.ps1 with two named switch parameters: -Debug and -Clear. When executing it remotely via Invoke-Command with the -FilePath parameter, passing these parameters causes errors. This is because the -ArgumentList parameter is designed to work with scriptblocks, not directly with file paths.

Solution 1: Using Scriptblocks with Parameter Duplication

The most straightforward approach is to wrap script execution in a scriptblock and define parameters within it. For example:

Invoke-Command -ComputerName (Get-Content C:\Scripts\Servers.txt) {
    param($Debug=$False, $Clear=$False)
    C:\Scripts\ArchiveEventLogs\ver5\ArchiveEventLogs.ps1
} -ArgumentList $False, $True

In this example, the scriptblock explicitly defines $Debug and $Clear parameters, passing values via -ArgumentList. This method allows precise control over parameter passing but requires manual duplication of all relevant script parameters.

Solution 2: Leveraging PSBoundParameters

To simplify parameter management, use PSBoundParameters for automatic binding. For example:

Invoke-Command -ComputerName (Get-Content C:\Scripts\Servers.txt) {
    param($one, $two, $Debug=$False, $Clear=$False)
    C:\Scripts\ArchiveEventLogs\ver5\ArchiveEventLogs.ps1 @PSBoundParameters
} -ArgumentList "uno", "dos", $false, $true

Here, @PSBoundParameters passes all bound parameters from the scriptblock to the target script, avoiding manual enumeration. This is particularly useful for scenarios with many or dynamic parameters.

Solution 3: Hard-Coding Parameter Passing

If parameter values can be hard-coded, call the script directly within the scriptblock with specified parameters. For example:

Invoke-Command -ComputerName $Env:ComputerName {
    param([bool]$Clear)
    C:\Scripts\ArchiveEventLogs\ver5\ArchiveEventLogs.ps1 "uno" "dos" -Debug -Clear:$Clear
} -ArgumentList $(Test-Path $Profile)

This example demonstrates passing switch parameters using the -Clear:$Clear syntax, where $Clear is a boolean value. It suits cases with fixed or simply derived parameter values.

Solution 4: Embedding Script Content

When the script is on the local machine and parameters include common ones (e.g., -Debug), embed the script content into a scriptblock. For example:

$script = [scriptblock]::create( @"
param(`$one,`$two,`$Debug=`$False,`$Clear=`$False)
&{ $(Get-Content C:\Scripts\ArchiveEventLogs\ver5\ArchiveEventLogs.ps1 -delimiter ([char]0)) } @PSBoundParameters
"@ )

Invoke-Command -Script $script -Args "uno", "dos", $false, $true

This method reads the script file content via Get-Content and creates a dynamic scriptblock, bypassing file path parameter limitations. It offers maximum flexibility but adds complexity.

Handling Variables and Environment

In remote execution, variable passing depends on their definition location. If variables are already defined on the remote computer (e.g., environment variables), use them directly:

&$Env:Script

If variables are local, pass them via -ArgumentList:

Invoke-Command -ComputerName $Env:ComputerName {
    param([String]$ScriptPath, [bool]$Clear)
    & $ScriptPath "uno" "dos" -Debug -Clear:$Clear
} -ArgumentList $ScriptPath, (Test-Path $Profile)

This ensures variable availability in the remote context.

Summary and Best Practices

The key to passing named parameters to Invoke-Command lies in understanding parameter binding mechanisms. For switch parameters, using scriptblocks with explicit definitions is the most reliable. Leveraging PSBoundParameters simplifies management, while embedding content suits complex scenarios. In practice, choose based on script location, parameter types, and execution environment. Also, note that common parameters (e.g., -Debug) may be auto-bound, requiring consideration in script design.

With these techniques, users can efficiently pass named parameters in PowerShell remote execution, enhancing script flexibility and maintainability.