Powershell Windows

1---
2name: powershell-windows
3description: PowerShell Windows patterns. Critical pitfalls, operator syntax, error handling.
4allowed-tools: Read, Write, Edit, Glob, Grep, Bash
5---
6 
7# PowerShell Windows Patterns
8 
9> Critical patterns and pitfalls for Windows PowerShell.
10 
11---
12 
13## 1. Operator Syntax Rules
14 
15### CRITICAL: Parentheses Required
16 
17| ❌ Wrong | ✅ Correct |
18|----------|-----------|
19| `if (Test-Path "a" -or Test-Path "b")` | `if ((Test-Path "a") -or (Test-Path "b"))` |
20| `if (Get-Item $x -and $y -eq 5)` | `if ((Get-Item $x) -and ($y -eq 5))` |
21 
22**Rule:** Each cmdlet call MUST be in parentheses when using logical operators.
23 
24---
25 
26## 2. Unicode/Emoji Restriction
27 
28### CRITICAL: No Unicode in Scripts
29 
30| Purpose | ❌ Don't Use | ✅ Use |
31|---------|-------------|--------|
32| Success | ✅ ✓ | [OK] [+] |
33| Error | ❌ ✗ 🔴 | [!] [X] |
34| Warning | ⚠️ 🟡 | [*] [WARN] |
35| Info | ℹ️ 🔵 | [i] [INFO] |
36| Progress | ⏳ | [...] |
37 
38**Rule:** Use ASCII characters only in PowerShell scripts.
39 
40---
41 
42## 3. Null Check Patterns
43 
44### Always Check Before Access
45 
46| ❌ Wrong | ✅ Correct |
47|----------|-----------|
48| `$array.Count -gt 0` | `$array -and $array.Count -gt 0` |
49| `$text.Length` | `if ($text) { $text.Length }` |
50 
51---
52 
53## 4. String Interpolation
54 
55### Complex Expressions
56 
57| ❌ Wrong | ✅ Correct |
58|----------|-----------|
59| `"Value: $($obj.prop.sub)"` | Store in variable first |
60 
61**Pattern:**
62```
63$value = $obj.prop.sub
64Write-Output "Value: $value"
65```
66 
67---
68 
69## 5. Error Handling
70 
71### ErrorActionPreference
72 
73| Value | Use |
74|-------|-----|
75| Stop | Development (fail fast) |
76| Continue | Production scripts |
77| SilentlyContinue | When errors expected |
78 
79### Try/Catch Pattern
80 
81- Don't return inside try block
82- Use finally for cleanup
83- Return after try/catch
84 
85---
86 
87## 6. File Paths
88 
89### Windows Path Rules
90 
91| Pattern | Use |
92|---------|-----|
93| Literal path | `C:\Users\User\file.txt` |
94| Variable path | `Join-Path $env:USERPROFILE "file.txt"` |
95| Relative | `Join-Path $ScriptDir "data"` |
96 
97**Rule:** Use Join-Path for cross-platform safety.
98 
99---
100 
101## 7. Array Operations
102 
103### Correct Patterns
104 
105| Operation | Syntax |
106|-----------|--------|
107| Empty array | `$array = @()` |
108| Add item | `$array += $item` |
109| ArrayList add | `$list.Add($item) | Out-Null` |
110 
111---
112 
113## 8. JSON Operations
114 
115### CRITICAL: Depth Parameter
116 
117| ❌ Wrong | ✅ Correct |
118|----------|-----------|
119| `ConvertTo-Json` | `ConvertTo-Json -Depth 10` |
120 
121**Rule:** Always specify `-Depth` for nested objects.
122 
123### File Operations
124 
125| Operation | Pattern |
126|-----------|---------|
127| Read | `Get-Content "file.json" -Raw | ConvertFrom-Json` |
128| Write | `$data | ConvertTo-Json -Depth 10 | Out-File "file.json" -Encoding UTF8` |
129 
130---
131 
132## 9. Common Errors
133 
134| Error Message | Cause | Fix |
135|---------------|-------|-----|
136| "parameter 'or'" | Missing parentheses | Wrap cmdlets in () |
137| "Unexpected token" | Unicode character | Use ASCII only |
138| "Cannot find property" | Null object | Check null first |
139| "Cannot convert" | Type mismatch | Use .ToString() |
140 
141---
142 
143## 10. Script Template
144 
145```powershell
146# Strict mode
147Set-StrictMode -Version Latest
148$ErrorActionPreference = "Continue"
149 
150# Paths
151$ScriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
152 
153# Main
154try {
155    # Logic here
156    Write-Output "[OK] Done"
157    exit 0
158}
159catch {
160    Write-Warning "Error: $_"
161    exit 1
162}
163```
164 
165---
166 
167> **Remember:** PowerShell has unique syntax rules. Parentheses, ASCII-only, and null checks are non-negotiable.
168