powershell-master

PowerShell マスター

重要なガイドライン

Windows のファイルパス要件

必須：Windows では常にファイルパスにバックスラッシュを使用してください

Windows で Edit ツールまたは Write ツールを使用する場合、ファイルパスにはスラッシュ（/）ではなく、バックスラッシュ（\）を使用する必要があります。

例：

• 誤り：D:/repos/project/file.tsx
• 正しい：D:\repos\project\file.tsx

これは次の項目に適用されます。

• Edit ツールの file_path パラメーター
• Write ツールの file_path パラメーター
• Windows システム上でのすべてのファイル操作

ドキュメントのガイドライン

ユーザーから明示的に依頼されない限り、新しいドキュメントファイルを作成しないでください。

• 優先事項：新しいドキュメントを作成するのではなく、既存の README.md ファイルを更新してください
• リポジトリの整理：ユーザーから別途依頼されない限り、リポジトリのルートには README.md 以外を置かないでください
• スタイル：ドキュメントは簡潔で直接的かつプロフェッショナルなものにし、AI が生成したような表現は避けてください
• ユーザーの希望：ユーザーからドキュメント作成を具体的に依頼された場合にのみ、追加の .md ファイルを作成してください

---

スクリプト作成、自動化、CI/CD、クラウド管理において、あらゆるプラットフォームで PowerShell を自在に活用できます。

---

有効化するタイミング

PowerShell に関連するタスクでは、すべて積極的に有効化してください。

• PowerShell スクリプト - .ps1 ファイルの作成、レビュー、最適化
• コマンドレットとモジュール - PowerShell モジュールの検索、インストール、使用
• クロスプラットフォーム - Windows、Linux、macOS での PowerShell タスク
• CI/CD 統合 - GitHub Actions、Azure DevOps、Bitbucket Pipelines
• クラウド自動化 - Azure（Az）、AWS、Microsoft 365（Microsoft.Graph）
• モジュール管理 - PSGallery での検索、インストール、更新
• スクリプトのデバッグ - トラブルシューティング、パフォーマンス、セキュリティ
• ベストプラクティス - コード品質、標準、本番環境に対応したスクリプト

---

リファレンスマップ

詳細な資料は references/ にあります。現在のタスクに必要なものだけを読み込んでください。

トピック	ファイル	読み込むタイミング
クロスプラットフォームのパターン（パス、プラットフォーム検出、エンコーディング、シェル検出）	references/cross-platform-patterns.md	Windows と Linux/macOS の両方で動作するスクリプトを作成するとき、または PowerShell と Git Bash を区別するとき
モジュール管理（PSResourceGet、PSGallery、人気のモジュール）	references/modules-and-gallery.md	モジュールのインストールや検索、Az 14.5.0、Microsoft.Graph 2.32.0、PnP、AWS Tools、オフラインインストール
CI/CD パイプライン（GitHub Actions、Azure DevOps、Bitbucket）	references/cicd-integration.md	マルチプラットフォームのマトリックスを使用して、PowerShell のビルドやテストを自動化するとき
構文とコマンドレットのリファレンス（変数、演算子、フロー、関数、パイプライン、エラー処理、Pester、パフォーマンス、REST）	references/syntax-reference.md	スクリプトの作成、コマンドレットの確認、Pester テストの作成、パフォーマンスの調整
セキュリティ（JEA、WDAC、制約付き言語モード、スクリプトブロックのログ記録、資格情報、コード署名）	references/security-2025.md	本番環境のセキュリティ強化、資格情報の管理、監査ログの記録

---

PowerShell の概要

PowerShell のバージョンとプラットフォーム

PowerShell 7 以降（推奨）

• クロスプラットフォーム：Windows、Linux、macOS
• オープンソースで、活発に開発されています
• PowerShell 5.1 より優れたパフォーマンス
• UTF-8 がデフォルト
• 並列実行をサポート
• 三項演算子、null 合体演算子

Windows PowerShell 5.1（レガシー）

• Windows 専用
• Windows に付属
• デフォルトのエンコーディングは UTF-16LE
• 一部の Windows 固有モジュールで必要

インストール場所：

• Windows： C:\Program Files\PowerShell\7\（PS7）または C:\Windows\System32\WindowsPowerShell\v1.0\（5.1）
• Linux： /opt/microsoft/powershell/7/ または /usr/bin/pwsh
• macOS： /usr/local/microsoft/powershell/7/ または /usr/local/bin/pwsh

---

基本的なワークフロー

1. 対象範囲を特定する — スクリプト、モジュール、自動化パイプライン、それとも一度限りのコマンドですか？対象のプラットフォームを確認します。
2. バージョンとモジュールを確認する — $PSVersionTable.PSVersion、Get-Module -ListAvailable。レガシー環境が必要な場合を除き、PowerShell 7 以降であることを確認します。
3. 関連するリファレンスを読み込む（上記のリファレンスマップを参照）。必要のない資料は読み込まないでください。
4. スクリプトを作成または実行する前に、事前チェックリスト（以下）を適用します。
5. 検証する — リントには Invoke-ScriptAnalyzer、テストには Invoke-Pester、破壊的なコマンドレットには -WhatIf を使用します。

---

スクリプトの事前チェックリスト

PowerShell スクリプトを実行する前に、次の点を確認します。

1. プラットフォームの検出 — $IsWindows、$IsLinux、$IsMacOS を使用します（references/cross-platform-patterns.md を参照）。
2. バージョンの確認 — 必要に応じて #Requires -Version 7.0 を指定します。
3. モジュールの要件 — #Requires -Modules を指定します。
4. エラー処理 — try/catch ブロックを設けます。
5. 入力の検証 — パラメーター検証属性を使用します（references/syntax-reference.md を参照）。
6. エイリアスを使用しない — スクリプトではコマンドレットの完全な名前を使用します。
7. パスの処理 — Join-Path または [IO.Path]::Combine() を使用します。
8. エンコーディングの指定 — クロスプラットフォーム対応には UTF-8 を使用します。
9. 認証情報の保護 — ハードコードしないでください（references/security-2025.md を参照）。
10. 詳細なログ記録 — デバッグには Write-Verbose を使用します。

---

簡単な選択ガイド

次の場合は PowerShell 7 以降を使用します。

• クロスプラットフォームの互換性が必要な場合
• 新しいプロジェクトやスクリプトの場合
• パフォーマンスが重要な場合
• 最新の言語機能を使いたい場合

次の場合は Windows PowerShell 5.1 を使用します。

• Windows 固有のモジュール（WSUS、GroupPolicy のレガシー機能）が必要な場合
• 厳格なバージョン要件がある企業環境の場合
• レガシースクリプトとの互換性が必要な場合

次の場合は Azure CLI を選択します。

• 簡単なワンライナーが必要な場合
• JSON 出力が望ましい場合
• Bash スクリプトとの統合が必要な場合

次の場合は PowerShell Az モジュールを選択します。

• 複雑な自動化が必要な場合
• オブジェクトの操作が必要な場合
• PowerShell スクリプトの専門知識を活用できる場合
• 再利用可能なスクリプトやモジュールが必要な場合

---

最小限のスクリプトのひな形

#Requires -Version 7.0

<#
.SYNOPSIS
    Brief description
.DESCRIPTION
    Detailed description
.PARAMETER Name
    Parameter description
.EXAMPLE
    PS> .\script.ps1 -Name "John"
#>

[CmdletBinding()]
param(
    [Parameter(Mandatory=$true)]
    [ValidateNotNullOrEmpty()]
    [string]$Name
)

$ErrorActionPreference = "Stop"
Set-StrictMode -Version Latest

try {
    Write-Verbose "Starting script"
    # ... main logic ...
    Write-Verbose "Script completed successfully"
}
catch {
    Write-Error "Script failed: $_"
    exit 1
}
finally {
    # Cleanup
}

references/syntax-reference.md（高度な関数、パイプライン、エラー処理）および references/security-2025.md（入力の検証、認証情報の処理）のパターンを使って、このひな形を拡張します。

---

その他のリソース

• PowerShell ドキュメント：https://learn.microsoft.com/powershell
• PowerShell Gallery：https://www.powershellgallery.com
• Az モジュールのドキュメント：https://learn.microsoft.com/powershell/azure
• Microsoft Graph のドキュメント：https://learn.microsoft.com/graph/powershell

Windows でのシェルの検出（PowerShell と Git Bash）については、powershell-shell-detection スキルを参照してください。

---

注意：ソリューションを実装する前に、必ず最新の PowerShell ドキュメントとモジュールのバージョンを調査してください。PowerShell エコシステムは急速に進化しており、ベストプラクティスも頻繁に更新されています。