windows-shell-reliability

Windows シェルの信頼性に関するパターン

PowerShell と CMD を介して Windows でコマンドを実行する際のベストプラクティスです。

使用する場面

Windows システムで実行するスクリプトや自動化の開発、デバッグを行うとき、特にファイルパス、文字エンコーディング、標準的な CLI ツールを扱う場合に、このスキルを使用します。

---

1. エンコーディングとリダイレクト

重大：PowerShell のバージョンによるリダイレクトの違い

古い Windows PowerShell のリリースでは、ネイティブコマンドの出力が書き換えられ、その後の処理に支障をきたす場合があります。PowerShell 7.4 以降では、標準出力をリダイレクトする際にバイトストリームが保持されるため、UTF-8 変換の回避策は、古いシェルの動作に対処する場合や、すでに読み取れなくなっているログファイルを扱う場合にのみ適用してください。

問題	症状	解決策
dotnet > log.txt	古い Windows PowerShell で view_file が失敗する	`Get-Content log.txt
npm run > log.txt	エラーを含む UTF-8 テキストログが必要	`npm run ... 2>&1

ルール： PowerShell 7.4 以降では、そのままネイティブのリダイレクトを使用し、古い Windows PowerShell のリダイレクトによってログが読み取れなくなった場合にのみ、明示的な UTF-8 変換を使用します。

---

2. パスとスペースの扱い

重大：引用符で囲む

Windows のパスにはスペースが含まれることがよくあります。

❌ 誤り	✅ 正しい
dotnet build src/my project/file.fsproj	dotnet build "src/my project/file.fsproj"
& C:\Path With Spaces\bin.exe	& "C:\Path With Spaces\bin.exe"

ルール： スペースが含まれる可能性のある絶対パスと相対パスは、必ず引用符で囲みます。

呼び出し演算子（&）

PowerShell では、実行ファイルのパスが引用符で始まる場合、必ず & 演算子を使用します。

パターン：

& "C:\Program Files\dotnet\dotnet.exe" build ...

---

3. バイナリとコマンドレットでよくある落とし穴

操作	❌ CMD スタイル	✅ PowerShell での選択肢
削除	del /f /q file	Remove-Item -Force file
コピー	copy a b	Copy-Item a b
移動	move a b	Move-Item a b
ディレクトリの作成	mkdir folder	New-Item -ItemType Directory -Path folder

ヒント： PowerShell で ls、cat、cp などの CLI エイリアスを使うのは通常問題ありませんが、スクリプトでは完全なコマンドレットを使うほうが堅牢です。

---

4. Dotnet CLI の信頼性

ビルド速度と一貫性

コンテキスト	コマンド	理由
高速な反復	dotnet build --no-restore	冗長な nuget の復元をスキップします。
クリーンビルド	dotnet build --no-incremental	インクリメンタルコンパイルを無効にします。古い出力が疑われる場合は、別途クリーン処理を行ってください。
バックグラウンド	Start-Process dotnet -ArgumentList 'run' -RedirectStandardOutput output.txt -RedirectStandardError error.txt	シェルをブロックせずにアプリを起動し、ログを保持します。

---

5. 環境変数

シェル	構文
PowerShell	$env:VARIABLE_NAME
CMD	%VARIABLE_NAME%

---

6. 長いパス

Windows では、既定でパスの長さが 260 文字に制限されています。

修正方法： 長いパスのエラーが発生した場合は、拡張パスプレフィックスを使用します： \\?\C:\Very\Long\Path\...

---

7. シェルエラーのトラブルシューティング

エラー	考えられる原因	修正方法
The term 'xxx' is not recognized	パスが $env:PATH に含まれていない	絶対パスを使用するか、PATH を修正します。
Access to the path is denied	ファイルが使用中、またはアクセス許可がない	所有者とロックを確認し、許可されたプロセスのみ停止します。既定の対処法として昇格を使用しないでください。
Encoding mismatch	古いシェルのリダイレクトによって出力が書き換えられた	ファイルを UTF-8 として再エクスポートするか、`2>&1

---

制限事項

• このスキルは、タスクが上記の説明に明確に該当する場合にのみ使用してください。
• 出力を、環境固有の検証、テスト、専門家によるレビューの代わりとして扱わないでください。
• 必要な入力、アクセス許可、安全上の境界、成功基準が不足している場合は、作業を中止して確認を求めてください。