PowerShellの引数設計とモジュール化の知識マップ(知識グラフ)
type: Dataset
description: PowerShellスクリプトを人に渡せる品質にするには、paramブロックに[CmdletBinding()]を付けて高度な関数にし、共通パラメーターを自動的に使えるようにすることが出発点になる。必須引数は[Parameter(Mandatory)]で渡し忘れによる既定値実行を防ぎ、ValidateSetなどの検証属性は形式が不正な値を実行前に弾いて途中まで実行されてから壊れる事故を防ぐ。パイプライン入力を受ける関数はValueFromPipelineとprocessブロックを組み合わせないと最後の1件しか処理されない罠があり、変更系の関数はSupportsShouldProcessで-WhatIfによる意図しない実行の防止を組み込む。複数スクリプトで使う共通処理は.psm1モジュールに切り出してExport-ModuleMemberで公開範囲を明示し、PSModulePath配下に置くと自動読み込みされ、配る段階でモジュールマニフェストを追加する。

paramブロック
type: Concept
definition: 関数やスクリプトの引数を宣言するPowerShellの構文要素で、型・既定値・各種属性をパラメーターごとに指定できる。
alternative label: Param Block

.psm1スクリプトモジュール
type: Concept
definition: 関数を書いたファイルを.psm1拡張子で保存するだけで作れるPowerShellのスクリプトモジュール形式。
alternative label: PowerShell Script Module
configured by: $env:PSModulePath(モジュールの探索パス)

[Parameter(Mandatory)]
type: Concept
definition: 引数を必須にする属性で、指定し忘れた呼び出しは対話実行では入力を促され、無人実行では失敗する。
alternative label: 必須パラメーター
requires: paramブロック
prevents: 必須引数の渡し忘れによる既定値実行

検証属性(ValidateSet/ValidateRange/ValidateScript等)
type: Concept
definition: パラメーター宣言に検証条件を持たせる一群の属性で、検証は関数本体の実行前に行われ、失敗すると関数は呼び出されない。
alternative label: Validation Attributes
alternative label: ValidateNotNullOrEmpty
alternative label: ValidatePattern
requires: paramブロック
prevents: 途中まで実行されてから壊れる事故

[switch]パラメーター
type: Concept
definition: 指定の有無だけで$trueまたは$falseになるオン/オフ引数の宣言方法。
alternative label: Switch Parameter
requires: paramブロック

ValueFromPipelineとprocessブロック
type: Concept
definition: パイプラインから流れてくる値を1件ずつ関数に受け取らせるための、パラメーター属性ValueFromPipelineとprocessブロックの組み合わせ。
alternative label: パイプライン入力
requires: paramブロック
prevents: 最後の1件しか処理されない罠

[CmdletBinding()]属性
type: Concept
definition: 関数やスクリプトに付けることで、コンパイル済みコマンドレットと同様の「高度な関数」として動作させ、共通パラメーターや$PSCmdletを自動的に使えるようにするPowerShellの属性。
alternative label: CmdletBindingAttribute
alternative label: 高度な関数
requires: paramブロック
implements: 共通パラメーター
prevents: タイプミス引数の黙殺

共通パラメーター
type: Concept
definition: [CmdletBinding()]を付けた高度な関数に自動的に追加される、-Verbose・-Debug・-WarningAction・-InformationAction・-ErrorActionなどのパラメーター群。
alternative label: Common Parameters

SupportsShouldProcessと-WhatIf/-Confirm
type: Concept
definition: [CmdletBinding(SupportsShouldProcess)]を宣言すると自動で追加される-WhatIf/-Confirmパラメーターと、$PSCmdlet.ShouldProcess()による実行可否の分岐の仕組み。
alternative label: ShouldProcess
alternative label: WhatIf
requires: [CmdletBinding()]属性
mitigates: 変更系処理の意図しない実行

最後の1件しか処理されない罠
type: Concept
definition: パイプライン入力を受ける高度な関数がbegin/process/endを1つも書かないと、本体はendブロック扱いになりパイプラインで複数件を流しても最後の1件しか処理されない典型的な事故。
alternative label: processブロック欠落バグ

ドットソース
type: Concept
definition: スクリプトのパスの前にドットと空白を付けて実行することで、そのスクリプト内で定義した関数・変数が呼び出し元のスコープにそのまま残る実行方法。
alternative label: Dot Sourcing
should precede: .psm1スクリプトモジュール

$env:PSModulePath(モジュールの探索パス)
type: Concept
definition: PowerShellがモジュールを検索するフォルダーの一覧を保持する環境変数。Windows PowerShell 5.1とPowerShell 7でユーザースコープの既定パスが異なる。
alternative label: PSModulePath

Export-ModuleMember
type: Concept
definition: スクリプトモジュールから外部へ公開する関数・エイリアスを明示するコマンドレットで、未指定時は全関数とエイリアスがエクスポートされる。
alternative label: 公開関数の明示

モジュールマニフェスト(.psd1)
type: Concept
definition: モジュールのバージョン番号・公開する関数・依存モジュール・対応するPowerShellのバージョンやエディションを宣言するファイル。New-ModuleManifestで雛形を作成する。
alternative label: .psd1
alternative label: New-ModuleManifest

PowerShell実行ポリシー
type: Concept
definition: PowerShellスクリプトの実行可否と署名要求を制御する設定。既定はクライアントOSでRestricted、Windows ServerとPowerShell 7ではRemoteSigned。
alternative label: Execution Policy
alternative label: RemoteSigned

コメントベースヘルプ
type: Concept
definition: .SYNOPSISや.EXAMPLEなどのキーワード付きコメントを関数やスクリプトに書くことで、Get-Helpが標準コマンドレットと同じ形式でヘルプを表示する仕組み。
alternative label: Comment-Based Help
alternative label: .SYNOPSIS/.EXAMPLE
recommended for: .psm1スクリプトモジュール

必須引数の渡し忘れによる既定値実行
type: Concept
definition: 必須のはずの引数を渡し忘れたまま、チェックがないために既定値や空の状態で処理が進んでしまう事故。
alternative label: Mandatory未指定の事故

途中まで実行されてから壊れる事故
type: Concept
definition: 引数の形式チェックを関数本体のif文で行うと、チェックより前に副作用が走ってしまい、不正な値のまま処理が一部実行された状態で壊れる事故。
alternative label: Partial Execution Failure

タイプミス引数の黙殺
type: Concept
definition: 高度な関数でない場合、未定義のパラメーター名や余分な位置引数を渡してもエラーにならず黙って無視され、既定値のまま動いてしまう事故。
alternative label: Unbound Argument Silent Ignore

変更系処理の意図しない実行
type: Concept
definition: 削除・移動・設定変更などの変更系処理が、影響範囲を確認する手段がないまま意図せず実行されてしまうこと。
alternative label: Unintended Destructive Execution

subject: [Parameter(Mandatory)]
predicate: requires
object: paramブロック
description: [Parameter(Mandatory)]はparamブロック内のパラメーター宣言に付与する属性である
evidence: about functions advanced parameters
verified at: 2026-08-01
certainty: established

subject: 検証属性(ValidateSet/ValidateRange/ValidateScript等)
predicate: requires
object: paramブロック
description: ValidateSetなどの検証属性はparamブロック内のパラメーター宣言に付与する
evidence: about functions advanced parameters
verified at: 2026-08-01
certainty: established

subject: [switch]パラメーター
predicate: requires
object: paramブロック
description: [switch]パラメーターはparamブロック内で宣言する
evidence: about functions advanced parameters
verified at: 2026-08-01
certainty: established

subject: ValueFromPipelineとprocessブロック
predicate: requires
object: paramブロック
description: ValueFromPipelineはparamブロック内のパラメーター属性として宣言する
evidence: about functions advanced parameters
verified at: 2026-08-01
certainty: established

subject: [CmdletBinding()]属性
predicate: requires
object: paramブロック
description: [CmdletBinding()]はparamブロックの先頭に付与することで、その関数を高度な関数にする
evidence: about functions cmdletbindingattribute
verified at: 2026-08-01
certainty: established

subject: [CmdletBinding()]属性
predicate: implements
object: 共通パラメーター
description: [CmdletBinding()]を付けた関数は共通パラメーターの実装を担い、-Verboseや-ErrorActionなどが自動で使えるようになる
evidence: about commonparameters
verified at: 2026-08-01
certainty: established

subject: SupportsShouldProcessと-WhatIf/-Confirm
predicate: requires
object: [CmdletBinding()]属性
description: SupportsShouldProcessは[CmdletBinding()]のオプションとして宣言し、これにより-WhatIf/-Confirmが自動追加される
evidence: everything-about-shouldprocess
verified at: 2026-08-01
certainty: established

subject: ValueFromPipelineとprocessブロック
predicate: prevents
object: 最後の1件しか処理されない罠
description: ValueFromPipelineとprocessブロックを組み合わせて書けば、パイプラインで流した複数件のうち最後の1件しか処理されない罠を防げる
evidence: about functions advanced methods
verified at: 2026-08-01
certainty: established

subject: ドットソース
predicate: shouldPrecede
object: .psm1スクリプトモジュール
description: 1つのスクリプトを分割する程度ならドットソースで足り、2本目のスクリプトから同じ関数を使いたくなった時点でモジュール化に進むのが判断の目安である
evidence: about scripts
verified at: 2026-08-01
certainty: established

subject: .psm1スクリプトモジュール
predicate: configuredBy
object: $env:PSModulePath(モジュールの探索パス)
description: モジュール名と同名のフォルダーを作ってPSModulePath配下に置けば、Import-Module不要で自動読み込みされる
evidence: about psmodulepath
verified at: 2026-08-01
certainty: established

subject: .psm1スクリプトモジュール
predicate: uses
object: Export-ModuleMember
description: 公開する関数の範囲を明示的に絞りたい場合、Export-ModuleMemberで明示するのがベストプラクティスとされる(未指定時は全関数とエイリアスがエクスポートされる)
evidence: export-modulemember
verified at: 2026-08-01
certainty: context-dependent

subject: モジュールマニフェスト(.psd1)
predicate: requires
object: .psm1スクリプトモジュール
description: RootModuleに.psm1スクリプトモジュールを指定する場合、モジュールマニフェストはその.psm1本体の存在を前提に作られる。RootModuleがバイナリモジュール(.dll)やマニフェストのみの場合はこの前提は当てはまらない。
evidence: new-modulemanifest
verified at: 2026-08-01
certainty: context-dependent

subject: .psm1スクリプトモジュール
predicate: requires
object: PowerShell実行ポリシー
description: 共有フォルダー配布したモジュールやスクリプトの実行は、実行ポリシー次第で拒否されることがある
evidence: about execution policies
verified at: 2026-08-01
certainty: context-dependent

subject: コメントベースヘルプ
predicate: recommendedFor
object: .psm1スクリプトモジュール
description: 他人に渡す・配布するモジュールにはコメントベースヘルプを書き、Get-Helpを効かせることが本記事の推奨である
evidence: about comment based help
verified at: 2026-08-01
certainty: established

subject: [Parameter(Mandatory)]
predicate: prevents
object: 必須引数の渡し忘れによる既定値実行
description: [Parameter(Mandatory)]を付けると、指定し忘れた呼び出しは実行前に止まるか入力を促されるため、渡し忘れたまま既定値で動く事故を防げる
evidence: about functions advanced parameters
verified at: 2026-08-01
certainty: established

subject: 検証属性(ValidateSet/ValidateRange/ValidateScript等)
predicate: prevents
object: 途中まで実行されてから壊れる事故
description: 検証属性による形式チェックは関数本体の実行前に行われ失敗すれば本体は1行も実行されないため、途中まで実行されてから壊れる事故を防げる
evidence: about functions advanced parameters
verified at: 2026-08-01
certainty: established

subject: [CmdletBinding()]属性
predicate: prevents
object: タイプミス引数の黙殺
description: 高度な関数では未定義のパラメーター名や余分な位置引数を渡すとバインドが失敗するため、タイプミスが黙って無視される事故を防げる
evidence: about functions cmdletbindingattribute
verified at: 2026-08-01
certainty: established

subject: SupportsShouldProcessと-WhatIf/-Confirm
predicate: mitigates
object: 変更系処理の意図しない実行
description: SupportsShouldProcessによる-WhatIf/-Confirmで実行前に影響範囲を確認できるため、変更系処理が意図せず実行されるリスクを減らせる。ただし-WhatIfの伝播は呼び出し先のコマンドまで常に保証されるわけではなく、利用者が-WhatIfを付けて確認しなければ効果を発揮しない
evidence: everything-about-shouldprocess
verified at: 2026-08-01
certainty: established