PowerShellの 完全解説！初心者も使いこなせる5つの具体的な利用例を現在の環境で使うなら「Get-Helpは実行前にsyntax、parameter、example、注意事項を確認するための読み取りcommandです。旧記事の-Briefは有効なGet-Help parameterではないため使わず、通常表示、-Detailed、-Full、-Examples、-Parameter、-Onlineを目的別に選びます。」が基本方針です。対象はbuilt-in helpは端末内の更新状態に依存し、online helpと内容やlanguageが異なる場合があるケースです。local helpの確認はread-onlyで始め、Update-Helpを行う場合だけ変更履歴と再確認条件を記録します。
module versionとlocal helpの世代を確認する
Get-Helpでは、現在読み込まれているモジュール版とローカルに保存されたヘルプ版を分けて確認します。対象コマンドのSyntax、Parameter Sets、Examplesを表示し、オンライン資料と差がある場合は更新可否とネットワーク条件を確認します。変更操作を試す前に、必須引数と既定のパラメーターセットを特定します。
- Get-Command Get-Helpで実体とmoduleを確認する
- Get-Help Get-Help -Fullで利用中versionのparameterを確認する
- Get-Help commandの末尾に更新を促す表示がないか確認する
- online参照時は対象PowerShell versionとmodule versionをURLまたはpage選択で合わせる
概要・詳細・exampleを段階的に読む
Get-Help、Get-Commandは読み取りです。一方Update-Helpはnetwork通信とlocal help file更新を伴います。管理端末ではdownload元、proxy、変更時間帯を確認し、事前に現在のhelp表示とmodule versionを記録します。更新失敗時にsecurity設定を弱めず、offline save-help配布など組織の方法を使います。戻しが必要な場合はmodule自体を削除せず、端末imageまたは管理手順に従ってhelp contentを復元します。
updatable helpの対象と戻し先を記録する
- 存在しない-Brief parameterを使う
- help未更新をcommandの不具合と判断する
- online pageのversion selectorを見ない
- exampleの破壊的commandを対象確認なしで実行する
- Update-Help失敗時にTLSやcertificate検証を無効にする
parameter setを混ぜずsyntaxを組み立てる
概要とsyntaxを確認
Get-Help Get-Process既定表示は概要、syntax、関連linkなどを要約します。見つからない場合はGet-Commandで名前を確認し、module未導入とhelp未更新を分けます。
詳細と全情報を段階表示
Get-Help Get-Process -Detailed
Get-Help Get-Process -FullDetailedはparameter説明とexampleを拡張し、Fullは入力・出力型や注記まで含めます。大量出力はOut-Host -Pagingへpipeして読みます。
一つのparameterだけ確認
Get-Help Get-Process -Parameter Name必須、位置、pipeline入力、wildcard可否などを確認します。parameter名はwildcard指定もできますが、自動化に必要な項目は完全名で記録します。
exampleとonline helpを参照
Get-Help Get-Process -Examples
Get-Help Get-Process -Onlineexampleはコピーして即本番実行せず、対象、権限、versionを読み替えます。-Onlineはbrowserを開くため、閉域端末では利用できません。
help contentを更新
Update-Help -Module Microsoft.PowerShell.Management -UICulture en-US -WhatIfUpdate-Helpはdownloadと端末変更を伴います。最初に-WhatIfで対象を確認し、proxyや管理者権限、組織policyを満たす場合だけ承認済み手順で実行します。
network・culture・permission失敗を分離する
Get-Helpはcommandの存在を保証するものではなく、sessionでcommandを解決できることとhelp fileがあることの両方に影響されます。parameterの角括弧は通常、省略可や型を表すsyntax記号で、その文字を入力する意味ではありません。exampleは特定version時点の例なので、対象resource名、権限、既定値を自環境で確認します。
Get-Command -Syntaxでmetadataを照合する
Get-Help Get-Help -Parameter *で利用可能parameterを実機確認し、対象commandのSyntax、Parameters、Examples、Inputs、Outputs、Notesを順に読みます。作業手順書には参照したmodule versionとpage URLを記録し、command upgrade後に差分reviewします。変更手順ではhelp記載の確認方法とrollbackを別途testします。
Synopsisとparameter情報を現行moduleへ結び付ける
Get-Helpは概要、-Detailed、-Full、-Examples、-Parameter、-Onlineを目的別に使います。local helpが未更新でもcommand metadataは表示されるため、更新日とmodule versionを記録し、Update-Helpの失敗をsyntax不存在と混同しません。
Get-Processのhelp metadataをobject化する
$cmd=Get-Command Get-Process -ErrorAction Stop
$help=Get-Help $cmd.Name -Full
[pscustomobject]@{Module=$cmd.ModuleName;Version=$cmd.Version;Synopsis=$help.Synopsis;SyntaxCount=$help.Syntax.SyntaxItem.Count}help本文・parameter・更新可否を個別に扱う
- 現行helpを確認：対象commandのSynopsis、Syntax、Parametersが現在のmodule versionと一致する
- local本文不足：help本文が未導入なら簡易表示を返すため、0件ではなく更新不足として判定する
- Update-Help失敗：Update-Helpのnetwork、culture、permission errorはErrorRecordを記録し、-Onlineの公式pageで照合する
-Examplesのsampleは安全性や環境前提を自動検証しません。parameter setを跨いだ組合せを作らず、Get-Command -Syntaxとも照合します。Update-Help -WhatIfは対象確認であり、helpが更新された証拠ではありません。
culture違いと存在しないparameterを試す
Get-Help Get-Process -Parameter Id
Get-Help Get-Process -Parameter 'parameter-that-does-not-exist' -ErrorAction SilentlyContinue | Measure-Objectinstalled helpあり/なし、en-USとja-JP、online不可、存在しないparameterをtestします。module version、help category、更新結果、参照URLを記録し、sampleはread-only対象で実行します。
local helpが古くてもcommand metadataは取得できます。module version、help culture、更新結果を併記し、sampleの実行可否はGet-Command -Syntaxと公式online helpで別に判断します。
コメント