powershell-reliable（powershell 可靠）

PowerShell Reliable Execution

Execute commands reliably on Windows PowerShell. Avoid common pitfalls like && chaining, parameter swallowing, and session interruptions.

Problem Statement

Windows PowerShell differs from bash in critical ways:

Core Patterns

1. Safe Command Chaining

Wrong:

mkdir test && cd test && echo done

Right:

$ErrorActionPreference = 'Stop'
try {
    New-Item -ItemType Directory -Path test -Force
    Set-Location test
    Write-Host 'done'
} catch {
    Write-Error "Failed: $_"
    exit 1
}

2. Parameter Safety

Wrong:

git commit -m "message"

Right:

git commit -Message "message"
# Or use splatting:
$params = @{ Message = "message" }
git commit @params

3. Path Handling

Wrong:

$path = "C:/Users/name/file.txt"

Right:

$path = Join-Path $env:USERPROFILE "file.txt"
# Or use literal paths:
$path = 'C:\Users\
ame\file.txt'

4. Output Encoding

Wrong:

echo "text" > file.txt

Right:

"text" | Out-File -FilePath file.txt -Encoding UTF8

5. Session Continuity

For long-running commands:

# Start background job
$job = Start-Job -ScriptBlock {
    param($arg)
    # Long operation
} -ArgumentList $arg

# Wait with timeout
Wait-Job $job -Timeout 300

# Get results
if ($job.State -eq 'Completed') {
    Receive-Job $job
} else {
    Stop-Job $job
    Write-Warning "Job timed out"
}

Error Recovery

Retry Pattern

function Invoke-Retry {
    param(
        [scriptblock]$Command,
        [int]$MaxAttempts = 3,
        [int]$DelaySeconds = 2
    )
    
    $attempt = 0
    while ($attempt -lt $MaxAttempts) {
        try {
            $attempt++
            return & $Command
        } catch {
            if ($attempt -eq $MaxAttempts) { throw }
            Start-Sleep -Seconds $DelaySeconds
        }
    }
}

# Usage
Invoke-Retry -Command { Invoke-WebRequest -Uri $url } -MaxAttempts 3

Interruption Recovery

# Checkpoint pattern
$checkpointFile = ".checkpoint.json"

if (Test-Path $checkpointFile) {
    $state = Get-Content $checkpointFile | ConvertFrom-Json
    Write-Host "Resuming from step $($state.step)"
} else {
    $state = @{ step = 0 }
}

switch ($state.step) {
    0 { 
        # Step 1
        $state.step = 1
        $state | ConvertTo-Json | Out-File $checkpointFile
    }
    1 {
        # Step 2
        Remove-Item $checkpointFile
    }
}

Privacy Security

All execution is local:

• NO command logging to external services
• NO credential capture in scripts
• NO automatic upload of execution results
• Sensitive data handled via [SecureString]
• Checkpoint files stored in working directory only

Sensitive Data Filter: Before writing any checkpoint or log:

• Exclude Password, Token, Secret, ApiKey
• Use [SecureString] for credentials
• Never echo sensitive variables

Executable Completion Criteria

A PowerShell command execution is reliable if and only if:

Quick Reference

Common Cmdlet Mappings

Splatting Template

$params = @{
    Path = $filePath
    Encoding = 'UTF8'
    Force = $true
}
Set-Content @params

References

• references/privacy-checklist.md - Privacy security checklist
• Microsoft Docs: PowerShell Best Practices

Execute reliably. Recover gracefully.