TL;DR

まとめの表だけ見ればよい。

はじめに

PowerShellを業務でよく使います。ドキュメントに記載してある以下の表記を見るたび、[]の意味を忘れてしまうため備忘録としてまとめます。

Get-Item
    [-Path] <string[]>
    [-Filter <string>]
    [-Include <string[]>]
    [-Exclude <string[]>]
    [-Force]
    [-Credential <pscredential>]
    [-Stream <string[]>]

対象読者

PowerShellを使う人
ドキュメントをよく見る人
同じ悩みを抱えている人

実行環境

PowerShell 7.6.3

`[]`は何を表現しているのか？

以下の2つのことを表現しています。

値が必須 or 省略可能
パラメーター名が必須 or 省略可能

したがって、組み合わせとして4パターン存在します。

例外として、これら2つに当てはまらない「スイッチパラメーター」があります。

値：必須パラメーター名：必須

いきなりで申し訳ありませんが、このパターンを採用している関数がわかりません。
業務で使ってきた中でも出会ったことがないと思います。

値：必須パラメーター名：省略可能

Get-Item
    [-Path] <string[]>

パラメーター名のみが[]で囲われているものが対象です。

実際に値を省略して試してみると

「パスを入力してください」と注意されます。

パラメーター名の省略は問題ありません。

値：省略可パラメーター名：省略可

どっちも省略可ってどういう意味？と思うかもしれませんが、「必須項目でないけど、値を指定するときにはパラメーター名はいらないよ」ということです。

Get-ItemProperty
    [-Path] <String[]>
    [[-Name] <String[]>]

Get-ItemPropertyの場合、-Nameが該当します。
パラメーター名から型までが[]で囲まれ、さらにパラメーター名も[]で囲まれているものです。

「必須項目でない」の部分から見ていきます。

-Nameを指定せずとも、コマンドの実行が可能です。

「値を指定するときにはパラメーター名はいらないよ」も見ていきます。

第二引数を自動で-Nameに紐づけてくれています。

値：省略可パラメーター名：省略不可

値を指定するときはパラメーター名をつける必要があるパラメーターです。

Get-Item
    [-Path] <string[]>
    [-Filter <string>]

Get-Itemの場合、-Filterが該当します。
パラメーター名から型までが[]で囲まれただけのものです。

値の省略は2つ前の例で記載しているので、パラメーター名の省略ができないことを見ていきます。

ドキュメントで上から2番目に書いてあるとはいえ、名前を省略することはできません。

パラメーター名を指定することでコマンドを実行できました。

スイッチパラメーター

スイッチパラメーターの有無でコマンドの処理が変わります。

New-Item
    [-Path] <String[]>
    [-Force]

New-Itemの場合、-Forceが該当します。
型の記載のないパラメーターが該当します。

New-Itemの場合、-Forceがないと上書き不可です。

-Forceをつけると上書き可能になります。

まとめ

表にしてまとめると、以下の通りです。
※ここでの『外側の[]』は名前と型をまとめて囲む括弧のことです

外側の`[]`	パラメーター名の`[]`	型	分類	例
なし	あり	あり	必須・位置パラメーター	`[-Path] <string>`
なし	なし	あり	必須・名前付き	`-Path <string>`
あり	あり	あり	省略可・位置パラメーター	`[[-Path] <string>]`
あり	なし	あり	省略可・名前付き	`[-Path <string>]`

正直ここだけ見ればいいのではないかという気分になってきました。

補足：パラメーターの省略について

省略するのはやめとこう派です。
私が業務でPowerShellを使用する際に気を付けていることです。

個人のスクリプトや、ターミナルでちょこっと触る分には、パラメーターの省略は便利ですし活用しています。

ただ、継続的に利用するスクリプト、ほかのメンバーも保守する可能性のあるスクリプトについては省略しません。

理由としては、すべてのコマンドの位置パラメーターの順序を覚えられないからです。
「このコマンドの2番目のパラメーターは…」と調べることになるので、可読性が下がると考えています。

（同様の理由で%や?もスクリプトでは使いません。）