PowerShell Start-Process argumentlist escape '|' pipe character in a variable

Question

When running Start-Process with -ArgumentList and passing string array $configArgs, it has a string that contains a special character which is a pipe (|). The pipe character comes from the last variable $passwordtemp that is added with --windowsLogonPassword.

Because of the pipe character I'm getting the following error message,

"The filename, directory name, or volume label syntax is incorrect."

Any ideas how I can avoid this?

[CmdletBinding(SupportsShouldProcess, DefaultParameterSetName = "NoVersion")]
param(
    [parameter(Mandatory = $false)]
    [string]$AgentDirectory = [IO.Path]::Combine($env:USERPROFILE, "VSTSAgents"),
 
    [parameter(Mandatory = $false)]
    [string]$Work,
 
    [parameter(Mandatory = $false)]
    [string]$Name = [System.Environment]::MachineName + "-$(Get-Random)",
 
    [parameter(Mandatory = $false)]
    [string]$Pool = 'Default',
 
    [parameter(Mandatory = $true)]
    [string]$PAT,
 
    [parameter(Mandatory = $true)]
    [uri]$ServerUrl,
 
    [parameter(Mandatory = $false)]
    [switch]$Replace,
 
    [parameter(Mandatory = $false)]
    [pscredential]$LogonCredential,
 
    [parameter(Mandatory = $false)]
    [string]$Cache = [io.Path]::Combine($env:USERPROFILE, ".vstsagents")
)
 
if ($PSVersionTable.Platform -and $PSVersionTable.Platform -ne 'Win32NT') {
    throw "Not Implemented: Support for $($PSVersionTable.Platform), contributions welcome."
}
 
if ( $Verbose ) { $VerbosePreference = 'Continue' }
 
$existing = Get-VSTSAgent -AgentDirectory $AgentDirectory -NameFilter $Name
if ( $existing ) { 
    if ($Replace) { 
        Uninstall-VSTSAgent -NameFilter $Name -AgentDirectory $AgentDirectory -PAT $PAT -ErrorAction Stop
    }
    else { throw "Agent $Name already exists in $AgentDirectory" }
}
 
$findArgs = @{ 'Platform' = 'win' }
if ( $MinimumVersion ) { $findArgs['MinimumVersion'] = $MinimumVersion }
if ( $MaximumVersion ) { $findArgs['MaximumVersion'] = $MaximumVersion }
if ( $RequiredVersion ) { $findArgs['RequiredVersion'] = $RequiredVersion }
 
$agent = Find-VSTSAgent @findArgs | Sort-Object -Descending -Property Version | Select-Object -First 1
if ( -not $agent ) { throw "Could not find agent matching requirements." }
 
Write-Verbose "Installing agent at $($agent.Uri)"
 
$fileName = $agent.Uri.Segments[$agent.Uri.Segments.Length - 1]
$destPath = [IO.Path]::Combine($Cache, "$($agent.Version)\$fileName")
 
if ( -not (Test-Path $destPath) ) {
 
    $destDirectory = [io.path]::GetDirectoryName($destPath)
    if (!(Test-Path $destDirectory -PathType Container)) {
        New-Item "$destDirectory" -ItemType Directory | Out-Null
    }
 
    Write-Verbose "Downloading agent from $($agent.Uri)"
    try {  Start-BitsTransfer -Source $agent.Uri -Destination $destPath }
    catch { throw "Downloading $($agent.Uri) failed: $_" }
}
else { Write-Verbose "Skipping download as $destPath already exists." }
 
$agentFolder = [io.path]::Combine($AgentDirectory, $Name)
Write-Verbose "Unzipping $destPath to $agentFolder"
 
if ( $PSVersionTable.PSVersion.Major -le 5 ) {
    Add-Type -AssemblyName System.IO.Compression.FileSystem -ErrorAction Stop
}
 
[System.IO.Compression.ZipFile]::ExtractToDirectory($destPath, $agentFolder)
 
$configPath = [io.path]::combine($agentFolder, 'config.cmd')
$configPath = Get-ChildItem $configPath -ErrorAction SilentlyContinue
if ( -not $configPath ) { throw "Agent $agentFolder is missing config.cmd" }
 
[string[]]$configArgs = @('--unattended', '--url', "$ServerUrl", '--auth', `
        'pat', '--pool', "$Pool", '--agent', "$Name", '--runAsService')
if ( $Replace ) { $configArgs += '--replace' }
if ( $LogonCredential ) { $configArgs += '--windowsLogonAccount', $LogonCredential.UserName }
if ( $Work ) { $configArgs += '--work', $Work }
 
if ( -not $PSCmdlet.ShouldProcess("$configPath $configArgs", "Start-Process") ) { return }
 
$token = [System.Net.NetworkCredential]::new($null, $PAT).Password
$configArgs += '--token', $token
 
if ( $LogonCredential ) {
    $passwordtemp = [System.Net.NetworkCredential]::new($null, $LogonCredential.Password).Password
    $configArgs += '--windowsLogonPassword', $passwordtemp
        
}
 
$outFile = [io.path]::Combine($agentFolder, "out.log")
$errorFile = [io.path]::Combine($agentFolder, "error.log")
 
Write-Verbose "Registering $Name to $Pool at $ServerUrl"
Start-Process $configPath -ArgumentList $configArgs -NoNewWindow -Wait `
    -RedirectStandardOutput $outFile -RedirectStandardError $errorFile -ErrorAction Stop
 
if (Test-Path $errorFile) {
    Get-Content $errorFile  | Write-Error
}

Answer 1

There are two factors at play:

• A long-standing bug in Start-Process unfortunately requires use of embedded double-quoting around arguments that contain spaces, e.g. -ArgumentList '-foo', '"bar baz"' - see this answer.

• When calling a batch file (.cmd), the command line is - inappropriately - parsed as if it had been submitted from inside cmd.exe by cmd.exe, requiring space-less arguments that contain cmd.exe metacharacters such as | to either be double-quoted or for the metacharacters to be individually ^-escaped.

You can manually compensate for these behaviors as follows:

$configArgsEscaped = 
  switch -Regex ($configArgs) {
    '[ ^&|<>",;=()]' { '"{0}"' -f ($_ -replace '"', '""') }
    default          { $_ } # no double-quoting needed 
}

Now use -ArgumentList $configArgsEscaped in lieu of -ArgumentList $configArgs in your Start-Process call.