PowerShell Windows Patterns

Critical patterns and pitfalls for Windows PowerShell.

---

1. Operator Syntax Rules

CRITICAL: Parentheses Required

❌ Wrong	✅ Correct
if (Test-Path "a" -or Test-Path "b")	if ((Test-Path "a") -or (Test-Path "b"))
if (Get-Item $x -and $y -eq 5)	if ((Get-Item $x) -and ($y -eq 5))

Rule: Each cmdlet call MUST be in parentheses when using logical operators.

---

2. Encoding Compatibility

Prefer portable log markers

Purpose	❌ Don't Use	✅ Use
Success	✅ ✓	[OK] [+]
Error	❌ ✗ 🔴	[!] [X]
Warning	⚠️ 🟡	[*] [WARN]
Info	ℹ️ 🔵	[i] [INFO]
Progress	⏳	[...]

PowerShell supports Unicode. ASCII log markers are a portability choice, not a syntax requirement. For non-ASCII scripts read by Windows PowerShell 5.1, use UTF-8 with BOM; PowerShell 7 uses UTF-8 without BOM by default. Check the consuming tool before choosing file encoding.

---

3. Null Check Patterns

Always Check Before Access

❌ Wrong	✅ Correct
$array.Count -gt 0	($null -ne $array) -and (@($array).Count -gt 0)
$text.Length	if ($null -ne $text) { $text.Length }

---

4. String Interpolation

Complex Expressions

"Value: $($obj.prop.sub)" is valid subexpression interpolation. Store a complex expression in a variable when that improves readability.

Pattern:

$value = $obj.prop.sub
Write-Output "Value: $value"

---

5. Error Handling

ErrorActionPreference

Value	Use
Stop	Required cmdlet failures must enter catch
Continue	Report a non-terminating error and continue deliberately
SilentlyContinue	When errors expected

Try/Catch Pattern

• A return inside try is valid; finally still runs
• Use finally for cleanup
• Return after try/catch

---

6. File Paths

Windows Path Rules

Pattern	Use
Literal path	C:\Users\User\file.txt
Variable path	Join-Path $env:USERPROFILE "file.txt"
Relative	Join-Path $ScriptDir "data"

Rule: Use Join-Path for cross-platform safety.

---

7. Array Operations

Correct Patterns

Operation	Syntax
Empty array	$array = @()
Add item	$array += $item
ArrayList add	`$list.Add($item)

---

8. JSON Operations

CRITICAL: Depth Parameter

❌ Wrong	✅ Correct
ConvertTo-Json	ConvertTo-Json -Depth 10

Rule: Always specify -Depth for nested objects.

File Operations

Operation	Pattern
Read	`Get-Content "file.json" -Raw
Write	`$data

# Strict mode
Set-StrictMode -Version Latest
$ErrorActionPreference = "Stop"

# Paths
$ScriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path

# Main
try {
    # Cmdlet logic here; check $LASTEXITCODE after native executables.
    Write-Output "[OK] Done"
    exit 0
}
catch {
    Write-Warning "Error: $_"
    exit 1
}