Proper Methods for Passing Boolean Values to PowerShell Scripts from Command Prompt

Problem Background and Error Analysis

When invoking PowerShell scripts from Windows batch files, developers frequently encounter failures in boolean parameter passing. A typical error scenario is as follows:

C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe -NoProfile -File .\RunScript.ps1 -Turn 1 -Unify $false

Executing this command produces a parameter transformation error:

Cannot process argument transformation on parameter 'Unify'. Cannot convert value "System.String" to type "System.Boolean", parameters of this type only accept booleans or numbers, use $true, $false, 1 or 0 instead.

Root Cause Analysis

PowerShell's -File parameter has significant limitations when processing script arguments. When invoking scripts with -File, PowerShell does not perform full expression evaluation on parameter values, treating them instead as raw strings. This means $false is not interpreted as the boolean value false, but is passed to the script as the literal string "$false".

To verify this behavior, create a simple test function:

function Test-BooleanParameter {
    param([bool]$TestParam)
    Write-Output "Parameter value: $TestParam"
    Write-Output "Parameter type: $($TestParam.GetType())"
}

When called with a string parameter:

Test-BooleanParameter -TestParam '$false'

This produces the same parameter transformation error, confirming the string-to-boolean conversion failure.

Solution 1: Using -Command Parameter

The most direct solution is to use the -Command parameter instead of -File. -Command treats the entire command line as a PowerShell script and performs full expression evaluation on all components.

Modified invocation method:

powershell.exe -NoProfile -Command ".\RunScript.ps1 -Turn 1 -Unify $false"

In this approach, $false is correctly parsed as the boolean value false within the PowerShell environment before being passed to the script parameters. This method ensures proper type conversion of parameter values.

Solution 2: Using Switch Parameters (Recommended)

A more PowerShell-idiomatic approach is to use switch parameters. Switch parameters are special boolean parameters where their presence indicates true and absence indicates false.

Modified script parameter definition:

param (
    [int]$Turn,
    [switch]$Unify
)

Corresponding invocation method:

powershell.exe -NoProfile -File .\RunScript.ps1 -Turn 1 -Unify

In this mode, simply including the -Unify parameter in the command line sets it to true, while omitting it defaults to false. This approach not only resolves type conversion issues but also makes script invocation more concise and intuitive.

Deep Understanding of Parameter Processing Mechanism

PowerShell's parameter binding system employs type converter mechanisms. When parameters are declared with specific types, PowerShell attempts to convert input values to the target type. For boolean types, valid inputs include:

• Boolean literals: $true, $false
• Numbers: 1 (true), 0 (false)
• Boolean objects

When using the -File parameter, parameter values are not processed by PowerShell's expression parser before being passed to the script, so $false remains in string form and fails type validation.

Practical Application Examples

Consider a practical configuration script scenario:

param(
    [string]$ConfigPath,
    [switch]$Force,
    [switch]$Verbose
)

if ($Force) {
    Write-Output "Force execution mode enabled"
}

if ($Verbose) {
    Write-Output "Verbose output mode enabled"
}

# Main logic...

Invocation examples:

# Using -Command approach
powershell.exe -Command ".\ConfigScript.ps1 -ConfigPath 'C:\config.xml' -Force $true -Verbose $false"

# Using switch parameter approach (recommended)
powershell.exe -File .\ConfigScript.ps1 -ConfigPath "C:\config.xml" -Force -Verbose

Best Practice Recommendations

Based on the above analysis, the following best practices are recommended:

1. Prefer switch parameters: For boolean configuration options, switch parameters are the optimal choice, avoiding type conversion issues while providing a clean API.
2. Choose execution mode appropriately: In batch invocation scenarios, use -Command if complex expressions must be passed; use -File for simple parameter passing as it's more efficient.
3. Provide clear documentation: Clearly document parameter types and expected invocation methods in script help.
4. Consider backward compatibility: If scripts need to support multiple invocation methods, include appropriate type checking and conversion logic in parameter processing.

By understanding and applying these methods, developers can effectively resolve boolean parameter passing issues in PowerShell script invocation, improving script reliability and usability.