powershell-windows

PowerShell on Windows

PowerShell has a handful of sharp edges that bite predictably. The rules below are not stylistic preferences -- ignoring them produces parser errors or silent wrong behavior.

Group cmdlet calls inside conditions

When a cmdlet result feeds a logical operator, wrap the call in parentheses. The parser otherwise treats -or/-and as a parameter to the cmdlet.

# Breaks: -or is read as an argument to Test-Path
if (Test-Path $a -or Test-Path $b) { ... }

# Works: each call is its own grouped expression
if ((Test-Path $a) -or (Test-Path $b)) { ... }

# Same rule with a comparison on one side
if ((Get-Item $p) -and ($count -eq 5)) { ... }

Stick to ASCII in script output

Non-ASCII glyphs (emoji, check marks, box drawing) cause "Unexpected token" errors on many Windows consoles and code pages. Use bracketed ASCII tags instead.

Meaning	Avoid	Use
Success	check / tick marks	[OK] [+]
Failure	cross / red circle	[X] [!]
Warning	warning sign	[WARN] [*]
Info	info symbol	[INFO] [i]
In progress	hourglass	[...]

Guard against null before dereferencing

Touching a property or method on $null throws -- and under Set-StrictMode even reading an unset variable does. Check first.

# Risky
if ($items.Count -gt 0) { ... }
$len = $name.Length

# Safe
if ($items -and $items.Count -gt 0) { ... }
if ($name) { $len = $name.Length }

Pull deep expressions out of strings

Interpolating a multi-hop property chain inside a string is fragile. Assign it to a variable, then interpolate the variable.

# Fragile
Write-Output "City: $($order.customer.address.city)"

# Clear
$city = $order.customer.address.city
Write-Output "City: $city"

Choose the right error preference

$ErrorActionPreference sets how non-terminating errors behave:

Value	Fits
Stop	development -- fail loudly and early
Continue	production scripts that should push through
SilentlyContinue	spots where an error is expected and fine