知識マップ: Write-Hostをやめる ── PowerShellの出力ストリームとログ設計
記事「Write-Hostをやめる ── PowerShellの出力ストリームとログ設計」の主張を、概念と関係(エッジ)に分解した知識グラフの全体です。各関係には根拠・確認日・確度が付いています。
PowerShellには成功・エラー・警告・詳細・デバッグ・情報の6つの出力ストリームがあり、後続の処理へ渡るのは成功ストリームだけである。Write-Hostは情報ストリームに書き込むため6番でのリダイレクトや捕捉はできるが、既定で常に画面へ表示され続けるため、値を返す用途である成功ストリームの代わりには推奨されない。関数は内部で出力したすべてのオブジェクトを成功ストリームへ返すため、戻り値のあるコマンドを呼び捨てにすると関数の戻り値が汚れ、この問題は$null=…による出力の抑止で軽減できる。Write-VerboseやWrite-Warningなどは[CmdletBinding()]を付けた関数で共通パラメーターにより呼び出し側から表示・捕捉を制御でき、運用として記録したい出来事はWrite-Informationと構造化ログに、進捗表示はデータストリームではなくログに残せないためWrite-Progressと分けて扱う。
flowchart LR
accTitle: PowerShellの出力ストリームとログ設計の知識マップ
accDescr: PowerShellの6つの出力ストリームがWrite-HostやWrite-Verboseなど各書き込みコマンドとどう対応し、CmdletBindingと共通パラメーターによる制御、関数の戻り値の汚染、構造化ログやトランスクリプトへどうつながるかを示す図
powershell_output_stream["PowerShellの出力ストリーム"]
write_host["Write-Host"]
write_output["Write-Output"]
powershell_success_stream["成功ストリーム"]
write_verbose["Write-Verbose"]
write_debug["Write-Debug"]
write_warning["Write-Warning"]
write_information["Write-Information"]
write_error["Write-Error"]
cmdletbinding["[CmdletBinding()]属性"]
common_parameters["共通パラメーター"]
function_output_leak["関数の戻り値の汚染"]
null_assignment_suppression["$null=…による出力の抑止"]
structured_logging["構造化ログ(structured log)"]
write_progress["Write-Progress"]
start_transcript["Start-Transcript"]
write_output -->|"利用する"| powershell_success_stream
write_host -->|"用いるのは非推奨"| powershell_success_stream
write_host -.->|"利用する"| powershell_output_stream
write_verbose -->|"利用する"| powershell_output_stream
write_debug -->|"利用する"| powershell_output_stream
write_warning -->|"利用する"| powershell_output_stream
write_information -->|"利用する"| powershell_output_stream
write_error -->|"利用する"| powershell_output_stream
write_verbose -.->|"前提とする"| cmdletbinding
cmdletbinding -->|"実装を担う"| common_parameters
write_warning -->|"で構成できる"| common_parameters
write_verbose -->|"で構成できる"| common_parameters
write_debug -->|"で構成できる"| common_parameters
write_information -->|"で構成できる"| common_parameters
write_error -->|"で構成できる"| common_parameters
powershell_success_stream -.->|"原因になり得る"| function_output_leak
null_assignment_suppression -->|"軽減する"| function_output_leak
write_information -->|"推奨される対応"| structured_logging
write_progress -->|"用いるのは非推奨"| structured_logging
start_transcript -->|"利用する"| powershell_output_stream
概念間の関係(全20件)
図と同じ関係を文章でも列挙します。表示している文と機械可読な意味データ(RDFa)は同じ要素に載っています。確度が「確立した関係」のものは直接の関係として、「条件付きの関係」のものは成立条件つきの言明(rdf:Statement)として表現しています。
- Write-Outputは成功ストリームを利用します。
- Write-Hostを成功ストリームに用いることは推奨されません。
- Write-HostはPowerShellの出力ストリームを利用します。
- Write-VerboseはPowerShellの出力ストリームを利用します。
- Write-DebugはPowerShellの出力ストリームを利用します。
- Write-WarningはPowerShellの出力ストリームを利用します。
- Write-InformationはPowerShellの出力ストリームを利用します。
- Write-ErrorはPowerShellの出力ストリームを利用します。
- Write-Verboseは[CmdletBinding()]属性を前提とします。
- [CmdletBinding()]属性は共通パラメーターの実装を担います。
- Write-Warningは共通パラメーターで構成できます。
- Write-Verboseは共通パラメーターで構成できます。
- Write-Debugは共通パラメーターで構成できます。
- Write-Informationは共通パラメーターで構成できます。
- Write-Errorは共通パラメーターで構成できます。
- 成功ストリームは関数の戻り値の汚染の原因になることがあります。
- $null=…による出力の抑止は関数の戻り値の汚染を軽減します。
- Write-Informationは構造化ログ(structured log)に対する本記事の推奨です。
- Write-Progressを構造化ログ(structured log)に用いることは推奨されません。
- Start-TranscriptはPowerShellの出力ストリームを利用します。
主要概念の定義
機械可読データ
このページはサイトの知識グラフ(_data/knowledge/)から自動生成されています。誤りの指摘はお問い合わせからお願いします。