powershelllisted

# PowerShell 腳本規範 ## 編碼與版本目標 - 檔案編碼依全域規則 §2 Encoding Strategy（UTF-8 with BOM），本檔不另行定義。 - 新腳本預設以 **PowerShell 7+ (pwsh)** 為目標版本。 - 若腳本需在 Windows PowerShell 5.1 執行（如散佈到未安裝 pwsh 的機器、被 Windows 工作排程器以 `powershell.exe` 呼叫），必須遵守 5.1 語法邊界，並在腳本開頭以 `#Requires -Version 5.1` 標明。 ## 5.1 相容語法邊界 目標包含 5.1 時，下列 7+ 語法**禁止使用**： - Pipeline chain 運算子 `&&`、`||` → 改用 `if ($?)` 或檢查 `$LASTEXITCODE`。 - 三元運算子 `? :`、null 合併 `??`、null 條件 `?.` → 改用 `if/else` 與明確的 `$null` 檢查。 - `ForEach-Object -Parallel`。 - `Get-Content -AsByteStream` → 5.1 改用 `-Encoding Byte`。 - 自動變數 `$IsWindows`、`$IsLinux`（5.1 不存在，引用會因 StrictMode 報錯）。 僅目標 7+ 的腳本不受此限，允許使用上述語法。 ## 嚴格模式與錯誤處理（Crucial） - 腳本開頭必須宣告嚴格模式與錯誤偏好： ```powershell Set-StrictMode -Version Latest $ErrorActionPreference = 'Stop' ``` - 可預期且需處理的失敗，以 `try/catch` 包覆並在 `catch` 中給出具體錯誤訊息；不可吞掉例外後靜默繼續。 - 呼叫原生執行檔（`git`、`dotnet` 等）後，必須檢查 `$LASTEXITCODE`，失敗時終止或回報；原生命令失敗不會觸發 `$ErrorActionPreference = 'Stop'`。 - 腳本以 `exit 0` / `exit 1` 明確回傳結束碼，供 CI 與呼叫端判斷成敗。 ## 參數宣告 - 具參數的腳本與函式一律使用 `[CmdletBinding()]` 搭配 `param()` 區塊，不讀取 `$args`。 - 每個參數標明型別，必填參數加 `[Parameter(Mandatory)]`，可枚舉值用 `[ValidateSet()]`，路徑類參數視需要加 `[ValidateScript({ Test-Path $_ })]`。 - 會修改系統狀態（刪檔、改設定、寫入註冊表）的函式，加 `SupportsShouldProcess` 並在執行點呼叫 `$PSCmdlet.ShouldProcess()`，使呼叫端可用 `-WhatIf` 預演。 ```powershell [CmdletBinding(SupportsShouldProcess)] param( [Parameter(Mandatory)] [string]$TargetPath, [ValidateSet('Install', 'Uninstall')] [string]$Mode = 'Install' ) ``` ## 命名慣例 - 函式採 **Verb-Noun*