PowerShellでのヘルプの読み方

0. 動機

SeleniumやPSwritePDFを入れてみて、オンラインヘルプ(-online)が使えないコマンドレットに直面し、コンソールに表示されるヘルプをまともに読めるようにならないとなと思ったので調べて纏めてみました。
なお私は今でも全然初心者ですが、一番最初ヘルプの読み方全然わからなくてチンプンカンプンだったのでそういう方には多分役立つのではないかと思います。

1. Get-Helpのパラメータ

ヘルプを表示するならGet-Helpコマンドレットですが、いくつかパラメータがありそれによって表示内容が変わります。ヘルプをなんとなく読めるようになるとそれも自分で調べてわかると思いますが、ひとまずGet-Helpには例えば下記パラメータがあり、基本は-Fullパラメータを使うと便利、と覚えておくときっといいと思います。

• -Detailed (パラメータ未指定よりもちょっと詳しいヘルプが表示される)
• -Full (一番詳しいヘルプが表示される)
• -Examples (使用例がいくつか表示される)
• -Online (オンラインヘルプを表示)
• -Showwindow (-Fullパラメータと同じ内容を別Windowで表示)

詳細：https://learn.microsoft.com/ja-jp/powershell/module/microsoft.powershell.core/get-help?view=powershell-7.3

2. Get-Helpの-Fullのヘルプ

-Fullパラメータを指定した場合のコンソール上の出力は下記。上から順番にわかる範囲で説明をしていきます。

PS C:\Users\Username> Get-Help Get-Help -full

名前
    Get-Help

構文
    Get-Help [[-Name] <string>]  [<CommonParameters>]

    Get-Help [[-Name] <string>]  [<CommonParameters>]

    Get-Help [[-Name] <string>]  [<CommonParameters>]

    Get-Help [[-Name] <string>]  [<CommonParameters>]

    Get-Help [[-Name] <string>]  [<CommonParameters>]

    Get-Help [[-Name] <string>]  [<CommonParameters>]


パラメーター
    -Category <string[]>

        必須                         false
        位置                         名前付き
        パイプライン入力を許可する   false
        パラメーター セット名           (すべて)
        エイリアス                      なし
        動的                     false

    -Component <string[]>

        必須                         false
        位置                         名前付き
        パイプライン入力を許可する   false
        パラメーター セット名           (すべて)
        エイリアス                      なし
        動的                     false

    -Detailed

        必須                         true
        位置                         名前付き
        パイプライン入力を許可する   false
        パラメーター セット名           DetailedView
        エイリアス                      なし
        動的                     false

    -Examples

        必須                         true
        位置                         名前付き
        パイプライン入力を許可する   false
        パラメーター セット名           Examples
        エイリアス                      なし
        動的                     false

    -Full

        必須                         false
        位置                         名前付き
        パイプライン入力を許可する   false
        パラメーター セット名           AllUsersView
        エイリアス                      なし
        動的                     false

    -Functionality <string[]>

        必須                         false
        位置                         名前付き
        パイプライン入力を許可する   false
        パラメーター セット名           (すべて)
        エイリアス                      なし
        動的                     false

    -Name <string>

        必須                         false
        位置                         0
        パイプライン入力を許可する   true (ByPropertyName)
        パラメーター セット名           (すべて)
        エイリアス                      なし
        動的                     false

    -Online

        必須                         true
        位置                         名前付き
        パイプライン入力を許可する   false
        パラメーター セット名           Online
        エイリアス                      なし
        動的                     false

    -Parameter <string>

        必須                         true
        位置                         名前付き
        パイプライン入力を許可する   false
        パラメーター セット名           Parameters
        エイリアス                      なし
        動的                     false

    -Path <string>

        必須                         false
        位置                         名前付き
        パイプライン入力を許可する   false
        パラメーター セット名           (すべて)
        エイリアス                      なし
        動的                     false

    -Role <string[]>

        必須                         false
        位置                         名前付き
        パイプライン入力を許可する   false
        パラメーター セット名           (すべて)
        エイリアス                      なし
        動的                     false

    -ShowWindow

        必須                         true
        位置                         名前付き
        パイプライン入力を許可する   false
        パラメーター セット名           ShowWindow
        エイリアス                      なし
        動的                     false

    <CommonParameters>
        このコマンドレットは、次の共通パラメーターをサポートします: Verbose、
        Debug、ErrorAction、ErrorVariable、WarningAction、WarningVariable、
        OutBuffer, PipelineVariable、および OutVariable。詳細については、
        about_CommonParameters (https://go.microsoft.com/fwlink/?LinkID=113216)
        を参照してください。


入力
    System.String


出力
    System.Object

エイリアス
    なし


注釈
    Get-Help を実行しましたが、このコンピューターにこのコマンドレットのヘルプ ファイルは見つかりませんでした。ヘルプ
    の一部だけが表示されています。
        -- このコマンドレットを含むモジュールのヘルプ ファイルをダウンロードしてインストールするには、Update-Help を
    使用してください。
        -- このコマンドレットのヘルプ トピックをオンラインで確認するには、「Get-Help Get-Help -Online」と入力するか
    、
           https://go.microsoft.com/fwlink/?LinkID=113316 を参照してください。

項目1：名前

なんのひねりも無くコマンドレットの名前そのもの。

名前
    Get-Help

項目2：構文

下記コンソール上では同じものが6個並んでおり、それぞれをパラメーターセットといい、一緒に使えるパラメータの組合せを示しています。またそれぞれのパラメーターセットには名前がありますが、それは表示されておらず、特に覚える必要は無いと思います。

構文
    Get-Help [[-Name] <string>]  [<CommonParameters>]

    Get-Help [[-Name] <string>]  [<CommonParameters>]

    Get-Help [[-Name] <string>]  [<CommonParameters>]

    Get-Help [[-Name] <string>]  [<CommonParameters>]

    Get-Help [[-Name] <string>]  [<CommonParameters>]

    Get-Help [[-Name] <string>]  [<CommonParameters>]

上記だと「全部同じじゃん」となりますが、実際オンラインヘルプだと違う表示で、そっちの方が違いがわかりやすいと思うので下記に添付。

こう見ると各パラメータセットごとに使えるパラメータが異なることが分かると思います。いつでも使えるパラメータもあれば、一部のパラメータセットでしか使えないパラメータもあるとわかるかと思います。

このパラメータセットを知らないとうまくコマンドレットが動きません。

たとえはオンラインヘルプの上から2つ目のパラメータセットでは-Detailedという必須パラメータがあります。例えばこれを上から3つ目にある-Examplesパラメータとセットにして下記のように使うとエラーが出て動きません。
好きなパラメータをごちゃまぜにしても動きませんよ、ということみたいですね。

PS C:\Users\Username> Get-Help Get-Help -detailed -example
Get-Help : 指定された名前のパラメーターを使用してパラメーター セットを解決できません。
発生場所 行:1 文字:1
+ Get-Help Get-Help -detailed -example
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : InvalidArgument: (:) [Get-Help]、ParameterBindingException
    + FullyQualifiedErrorId : AmbiguousParameterSet,Microsoft.PowerShell.Commands.GetHelpCommand

また色々な括弧があり初見だとよくわからん、となると思いますがイメージでは下記を覚えればOKだと思います。

• 角かっこ[]:省略可能なパラメータ
• 山かっこ<>:パラメータの引数のデータ型

つまり下記の箇所は、-Nameパラメータも引数(String型)も省略可能である、ということを示しています。

[[-Name] <string>]

参考：https://tonari-it.com/windows-powershell-onlinehelp/

項目3：パラメータ

パラメータに関しては-Fullを抜き出すと下記です。
それぞれに関して簡単に説明していきます。

    -Full

        必須                         false
        位置                         名前付き
        パイプライン入力を許可する   false
        パラメーター セット名           AllUsersView
        エイリアス                      なし
        動的                     false

項目3-x. そもそものパラメータの種類

"パラメータ"と一言に言っても色々種類があります。
多分これを区別しておいた方が後々の説明が読みやすいと思うのでここにメモしておきます。

• 必須(Mandatory)パラメータ vs 省略可能(Optional)なパラメータ
  • ある構文において、コマンドレットの後に指定しないとコマンドレットが動かないパラメータが必須パラメータ。無くてもコマンドレットが動くパラメータが省略可能パラメータ。Get-Helpのオンラインヘルプの例だと2つ目の構文に関しては-Detailedパラメータが必須パラメータです。
• 名前付き(Named)パラメータ vs 位置指定(Positional)パラメータ
  • コマンドレットの後にパラメータ名をちゃんと指定しないと動かないパラメータが名前付きパラメータ。パラメータ名を指定せず値だけ入力し、その相対位置を示せば動くパラメータが位置指定パラメータ。-Detailedは名前付きパラメータです。
• スイッチパラメータ
  • 引数が不要でパラメータ名だけ指定すればOKなパラメータ。-Detailedは引数がいらないのでスイッチパラメータです。

参考：https://learn.microsoft.com/ja-jp/powershell/scripting/developer/cmdlet/types-of-cmdlet-parameters?view=powershell-7.3

項目3-1：「必須」

前述3-xのように所定の構文において必須か否かを示す箇所。Trueだと必須でFalseだと省略可能なパラメータということ。-Fullの場合は必須なパラメータではないということです。

項目3-2：「位置」

これも前述3-xに関連し、名前付きパラメータか位置パラメータかを示しています。
-Fullは名前付きスイッチパラメータなので、詳細なヘルプを見たい場合には絶対に-Fullをコマンドレットの後に書く必要があります。

一方位置が"0"となっている-Nameパラメータがありますが、これはパラメータ名が無くて値が1つだけコマンドレットの後にある場合、一番最初の値をPCは「-Nameパラメータの引数であると認識する」、ということを示しています。

項目3-3：「パイプライン入力を許可する」

恐らく私のような初心者だとなんとなーくパイプラインを使ってると思いますが、実はできるできないがあります。
そして恐らく「なぜパラメータごとにその可否が書かれているか？」がわからないかと思います。

ものすごく簡単に説明すると、パイプラインの前のオブジェクトが後のオブジェクトに渡される場合、漠然と後のコマンドレットに渡されるわけではなく、後のコマンドレットの所定のパラメータに渡ります。

なのでパラメータごとにこの可否が記載されているわけです。

-Fullの場合、falseなのでパイプラインの出力を受けることにはならない、ということですね。

-Nameの場合はパイプライン入力を許可することになってます。
"byPropertyName"とありこれがわからないと思いますが、これは「どのパラメータでパイプライン出力を受けるか」の判断基準(パラメーターバインディング)を示しています。他にbyValueもあります。
このバインディングについては説明が難しいのでここではしませんが、これを完全にわかってなくともヘルプ自体は大体読めるので大丈夫だとは思います。

なお詳細は下記書籍の2.8章の説明が分かりやすいです。

項目3-4：「パラメーターセット名」

構文の項目の際に既に説明済です。
オンラインヘルプでもパラメーターセット名って明確に記載がないと思いますが、ちゃんと把握したい場合には「構文」欄と「パラメーター」欄を比較しながら読むと何番目の構文がなんて名前なのかわかることにはわかると思います。

項目3-5：「エイリアス」(パラメータ)

エイリアスは雑な言い方だと略称です。Set-Locationコマンドレットだとcdが同じ意味ですね。
パラメーターの場合でも同様にエイリアスがあり、それがある場合には表示されるのだと思いますがGet-Helpコマンドレットのパラメータはどれもエイリアスがないということだと思います。

項目3-6：「動的」

ある所定の条件下で使えるパラメータを動的(Dynamic)パラメータといいます。
Get-Helpのパラメータは全て動的ではない、つまり静的(Static)なパラメータのようです。
多分私のような初心者レベルだとこれはこの程度の理解で問題ないと思います。

参考：https://winscript.jp/powershell/278

項目4：入力

コマンドレットの入力のデータ型を示しています。
Get-Helpコマンドの場合はString型である必要があるようです。
ここはパイプラインを使ったコードを考える場合にも参考になると思います。

入力
    System.String

項目5: 出力

コマンドレットの出力のデータ型を示しています。
Get-Helpコマンドの場合はObject型になるようです。
ここもパイプラインを使ったコードを考える場合にも参考になると思います。

出力
    System.Object

項目6：エイリアス (コマンドレット)

コマンドレットのエイリアスがあればここに表示されます。
Get-Helpの場合には無いみたいですね。

エイリアス
    なし

項目7：注釈

その他補足があればここに表示されるイメージです。

注釈
    Get-Help を実行しましたが、このコンピューターにこのコマンドレットのヘルプ ファイルは見つかりませんでした。ヘルプ
    の一部だけが表示されています。
        -- このコマンドレットを含むモジュールのヘルプ ファイルをダウンロードしてインストールするには、Update-Help を
    使用してください。
        -- このコマンドレットのヘルプ トピックをオンラインで確認するには、「Get-Help Get-Help -Online」と入力するか
    、
           https://go.microsoft.com/fwlink/?LinkID=113316 を参照してください。

おわりに

• 基本自分用のメモですがどなたかの役に立てば幸いです。
• ひとまずこの記事でヘルプの何が何なのかはざっくりわかるんじゃないかと思います。