powershell-windows

PowerShell Windows のパターン

Windows PowerShell の重要なパターンと注意点です。

---

1. 演算子の構文ルール

重要：括弧が必要です

❌ 誤り	✅ 正しい
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))

ルール： 論理演算子を使用する場合、各コマンドレットの呼び出しを必ず括弧で囲みます。

---

2. エンコーディングの互換性

移植性の高いログマーカーを優先します

目的	❌ 使用しない	✅ 使用する
成功	✅ ✓	[OK] [+]
エラー	❌ ✗ 🔴	[!] [X]
警告	⚠️ 🟡	[*] [WARN]
情報	ℹ️ 🔵	[i] [INFO]
進行状況	⏳	[...]

PowerShell は Unicode をサポートしています。ASCII のログマーカーは構文上の要件ではなく、移植性を考慮した選択です。Windows PowerShell 5.1 で読み込む非 ASCII のスクリプトには、BOM 付き UTF-8 を使用してください。PowerShell 7 では、既定で BOM なし UTF-8 が使われます。ファイルエンコーディングを選ぶ前に、読み込むツールを確認してください。

---

3. Null チェックのパターン

アクセス前に必ず確認します

❌ 誤り	✅ 正しい
$array.Count -gt 0	($null -ne $array) -and (@($array).Count -gt 0)
$text.Length	if ($null -ne $text) { $text.Length }

---

4. 文字列の補間

複雑な式

"Value: $($obj.prop.sub)" は有効な部分式の補間です。可読性が向上する場合は、複雑な式を変数に格納します。

パターン：

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

---

5. エラー処理

ErrorActionPreference

値	用途
Stop	必須のコマンドレットで発生したエラーを catch に渡します
Continue	非終端エラーを報告し、意図的に処理を続行します
SilentlyContinue	エラーが予想される場合に使用します

Try/Catch パターン

• try 内の return は有効です。finally は引き続き実行されます
• クリーンアップには finally を使用します
• try/catch の後に return します

---

6. ファイルパス

Windows のパスルール

パターン	用途
リテラルパス	C:\Users\User\file.txt
変数パス	Join-Path $env:USERPROFILE "file.txt"
相対パス	Join-Path $ScriptDir "data"

ルール： クロスプラットフォームで安全に使うため、Join-Path を使用します。

---

7. 配列操作

正しいパターン

操作	構文
空の配列	$array = @()
項目の追加	$array += $item
ArrayList への追加	`$list.Add($item)

---

8. JSON 操作

重要：Depth パラメーター

❌ 誤り	✅ 正しい
ConvertTo-Json	ConvertTo-Json -Depth 10

ルール： ネストされたオブジェクトには、必ず -Depth を指定します。

ファイル操作

操作	パターン
読み込み	`Get-Content "file.json" -Raw
書き込み	`$data

---

9. よくあるエラー

エラーメッセージ	原因	修正方法
"parameter 'or'"	括弧が不足しています	コマンドレットを () で囲みます
"Unexpected token"	解析または引用符のエラーです	報告されたトークンとファイルエンコーディングを確認します
"Cannot find property"	オブジェクトが Null です	先に Null かどうか確認します
"Cannot convert"	型が一致していません	入力を検証し、必要な型に変換します

---

10. スクリプトテンプレート

# 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
}

---

覚えておきましょう： シェルのバージョン、エンコーディング、Null の扱い、ネイティブコマンドの終了コードを確認してください。try/catch だけでは、ネイティブコマンドの失敗を例外に確実に変換できません。

参考資料：エンコーディング、引用符のルール。

使用する場面

Windows PowerShell または PowerShell 7 のスクリプトを作成またはデバッグするとき、特にコマンド式、エンコーディング、パス、エラー処理を扱う場合に使用します。

制限事項

• このスキルは、タスクが上記のスコープに明確に一致する場合にのみ使用してください。
• 出力を、環境固有の検証、テスト、専門家によるレビューの代替として扱わないでください。
• 必要な入力、権限、安全境界、成功基準が欠けている場合は、作業を中断して確認を求めてください。