powershell-expert

PowerShell エキスパート

Microsoft のベストプラクティスと PowerShell エコシステムを活用し、本番環境向けの高品質な PowerShell スクリプト、ツール、GUI を開発します。

クイックリファレンス

スクリプトの構成

#Requires -Version 5.1

<#
.SYNOPSIS
    Brief description.
.DESCRIPTION
    Detailed description.
.PARAMETER Name
    Parameter description.
.EXAMPLE
    Example-Usage -Name 'Value'
#>

[CmdletBinding()]
param(
    [Parameter(Mandatory, ValueFromPipeline)]
    [ValidateNotNullOrEmpty()]
    [string[]]$Name,

    [switch]$Force
)

begin {
    # One-time setup
}

process {
    foreach ($item in $Name) {
        # Per-item processing
    }
}

end {
    # Cleanup
}

関数のテンプレート

function Verb-Noun {
    [CmdletBinding(SupportsShouldProcess)]
    param(
        [Parameter(Mandatory, Position = 0)]
        [string]$Name,

        [Parameter(ValueFromPipelineByPropertyName)]
        [Alias('CN')]
        [string]$ComputerName = $env:COMPUTERNAME,

        [switch]$PassThru
    )

    process {
        if ($PSCmdlet.ShouldProcess($Name, 'Action')) {
            # Implementation
            if ($PassThru) { Write-Output $result }
        }
    }
}

ワークフロー

1. スクリプト開発

命名規則とパラメーター規約に従います。

• 承認済みの動詞を使った Verb-Noun 形式（Get-Verb）
• 検証属性による 強い型付け
• ValueFromPipeline による パイプラインのサポート
• 破壊的な操作には -WhatIf/-Confirm

詳細なガイドラインについては、best-practices.md をご覧ください。

2. GUI 開発

シンプルなダイアログには Windows Forms、複雑なインターフェイスには WPF/XAML を使用します。

Add-Type -AssemblyName System.Windows.Forms
Add-Type -AssemblyName System.Drawing

$form = New-Object System.Windows.Forms.Form -Property @{
    Text          = 'Title'
    Size          = New-Object System.Drawing.Size(400, 300)
    StartPosition = 'CenterScreen'
}

コントロール、イベント、テンプレートについては、gui-development.md をご覧ください。

3. PowerShell Gallery との連携

PSResourceGet を使ってモジュールを検索し、インストールします。

# Search gallery
Find-PSResource -Name 'ModuleName' -Repository PSGallery

# Install module
Install-PSResource -Name 'ModuleName' -Scope CurrentUser -TrustRepository

検索機能を強化するには、scripts/Search-Gallery.ps1 を使用します。

すべてのコマンドレットのリファレンスについては、powershellget.md をご覧ください。

主なパターン

エラー処理

try {
    $result = Get-Content -Path $Path -ErrorAction Stop
}
catch [System.IO.FileNotFoundException] {
    Write-Error "File not found: $Path"
    return
}
catch {
    throw
}

可読性を高めるスプラッティング

$params = @{
    Path        = $sourcePath
    Destination = $destPath
    Recurse     = $true
    Force       = $true
}
Copy-Item @params

パイプラインのベストプラクティス

# Stream output immediately
foreach ($item in $collection) {
    Process-Item $item | Write-Output
}

# Accept pipeline input
param(
    [Parameter(ValueFromPipeline)]
    [string[]]$InputObject
)
process {
    foreach ($obj in $InputObject) {
        # Process each
    }
}

モジュールの推奨

モジュールを推奨する際は、PowerShell Gallery を検索してください。以下はよく使われる候補です。推奨する前に、必ずモジュールの検証を行ってください。

カテゴリ	人気のモジュール
Azure	Az、Az.Compute、Az.Storage
テスト	Pester、PSScriptAnalyzer
コンソール	PSReadLine、Terminal-Icons
シークレット	Microsoft.PowerShell.SecretManagement
Web	Pode（Web サーバー）、PoshRSJob（非同期処理）
GUI	WPFBot3000、PSGUI

ドキュメントの参照

記憶に頼らず、最新の情報源に照らしてコマンドレットの構文とモジュールの利用可否を確認してください。learn.microsoft.com の PowerShell ページはすべて、公開されている MicrosoftDocs リポジトリ内の Markdown から生成されています。**レンダリング済みのページではなく、Markdown を取得してください。**ソースははるかに小さく、ナビゲーションや JavaScript がなく、構文ブロックとパラメーターテーブルがそのまま保持されています。

Raw Markdown ソース（WebFetch）

raw.githubusercontent.com に対して WebFetch ツールを使用します。以下のテンプレートから URL を直接作成してください。先に検索してはいけません。

コマンドの種類	URL テンプレート
コア PowerShell Get-ChildItem, Write-Output, Invoke-Command	https://raw.githubusercontent.com/MicrosoftDocs/PowerShell-Docs/main/reference/{version}/{Module}/{Cmdlet}.md
概念 about_Splatting, about_CommonParameters	https://raw.githubusercontent.com/MicrosoftDocs/PowerShell-Docs/main/reference/{version}/Microsoft.PowerShell.Core/About/{about_Topic}.md
Windows 専用 Get-ADUser, Get-DnsServerZone, Get-MpComputerStatus	https://raw.githubusercontent.com/MicrosoftDocs/windows-powershell-docs/main/docset/winserver2025-ps/{Module}/{Cmdlet}.md
ギャラリー／パッケージング Install-PSResource, Find-PSResource	https://raw.githubusercontent.com/MicrosoftDocs/powershell-docs-psget/main/powershell-gallery/powershellget-3.x/Microsoft.PowerShell.PSResourceGet/{Cmdlet}.md
サテライトモジュール Invoke-ScriptAnalyzer, Get-Secret	https://raw.githubusercontent.com/MicrosoftDocs/PowerShell-Docs-Modules/main/reference/ps-modules/{Module}/{Cmdlet}.md

{version} は 5.1、7.4、7.5、7.6、7.7 のいずれかです。コンテキストから判断して固定してください — #Requires、pwsh、ISE、または明記されたプラットフォームを確認します。手掛かりがない場合は、7.5 と 5.1 の両方を取得し、パラメーターに違いがあれば明記してください。エディションを誤ると、正しいように見えてもユーザーのシェルでは失敗する構文が返されます。

WebFetch へのプロンプト：構文ブロック全体、型と既定値を含むパラメーター表全体、および例を抽出してください。

URL の作成には、次の 3 つのルールがあります。

1. 大文字と小文字を区別します。 Raw のパスは、learn.microsoft.com とは異なり、大文字と小文字が区別されます。 .../activedirectory/Get-ADUser.md は 404 を返しますが、.../ActiveDirectory/Get-ADUser.md は 200 を返します。モジュール固有の大文字・小文字表記を維持してください。
2. フォルダーを指定してはいけません。 Raw が提供するのはファイルのみです。末尾が / の URL はすべて 404 を返します。ディレクトリー一覧を取得するエンドポイントはありません。
3. ページ URL を変換します。 github.com/{owner}/{repo}/blob/{branch}/{path} を raw.githubusercontent.com/{owner}/{repo}/{branch}/{path} に書き換えます。

コマンドレットを正しいリポジトリ、モジュール、バージョンフォルダーに割り当てる方法は、doc-sources.md に記載されています。モジュールの完全な一覧と 404 のトラブルシューティング表も掲載されています。正しいパスが明らかでない場合は、必ず参照してください。

フォールバックの手順

失敗した場合に限り、一度に 1 段階ずつ進めてください。

手順	ツール	使用する状況
1	WebFetch Raw Markdown	デフォルト — 常に最初に試す
2	WebFetch contents API https://api.github.com/repos/{owner}/{repo}/contents/{path}	フォルダー名が不明な場合。きれいに解析できるプレーンな JSON を返します。認証なしの場合は 1 時間あたり 60 リクエスト
3	WebFetch learn.microsoft.com	Raw ソースが存在しない場合（サードパーティ製モジュール、Learn のみの記事）
4	WebSearch	パスを導き出せない場合。検索クエリ：{Cmdlet-Name} site:learn.microsoft.com/en-us/powershell — その後、結果を Raw URL に変換して手順 1 に戻る
5	ローカル実行	ツールを利用できない場合。ユーザーに Get-Help {Cmdlet} -Full または Get-Command {Cmdlet} -Syntax の実行を依頼する

すべての手順が失敗した場合は、推測せず、不確実であることを明示してください。

「ライブドキュメントで確認できませんでした。次を実行して確認してください： Get-Command Cmdlet-Name -Syntax」

モジュールの確認

ギャラリーのパッケージには Markdown ソースがありません。WebFetch を使用して、一覧ページを直接取得してください。

• URL: https://www.powershellgallery.com/packages/{ModuleName}
• プロンプト: Extract: module name, latest version, last updated date, total downloads, and whether it shows any deprecation warning or 'unlisted' status

404 が返された場合、そのモジュールは存在しない可能性があります。{ModuleName} PowerShell module site:powershellgallery.com を WebSearch で検索して確認してください。両方のツールが利用できない場合は、scripts/Search-Gallery.ps1 -Name 'ModuleName' を実行してください。

シナリオ	要件
ユーザーがモジュール X の有無を尋ねている	ギャラリーで必ず確認してください
特定のモジュールを推奨する	存在し、非推奨ではないことを必ず確認してください
モジュールのバージョン要件を示す	ギャラリーで最新バージョンを必ず確認してください
正確なコマンドレット構文を提示する	raw Markdown での確認を推奨します
一般的なベストプラクティス	静的な参照情報で十分です

良い例（最新データで確認済み）：

「ImportExcel（v7.8.10、2024年10月更新、1,700万回以上ダウンロード）は、Excel をインストールせずにスプレッドシートを作成できる Export-Excel を提供します。」

悪い例（未確認）：

「Excel-Tools モジュールを使ってデータをエクスポートしてください。」← 存在しない可能性があります

レンダリングされたドキュメント

これらは手動で参照してください。取得時は、上記の raw ソースを優先してください。

リソース	URL
PowerShell のドキュメント	https://learn.microsoft.com/en-us/powershell/
モジュールブラウザー	https://learn.microsoft.com/en-us/powershell/module/
PowerShell Gallery	https://www.powershellgallery.com

参照ファイル

トピック	ファイル
ドキュメントのルーティング、raw URL マップ、404 のトラブルシューティング	references/doc-sources.md
命名、パラメーター、パイプライン、エラー処理、コードスタイル	references/best-practices.md
Windows Forms、WPF、コントロール、イベント、テンプレート	references/gui-development.md
モジュールの検索、インストール、更新、公開	references/powershellget.md

同梱スクリプト

スクリプト	用途
scripts/Search-Gallery.ps1	旧式の Find-Module による代替処理を備えた、書式付きの PowerShell Gallery 検索