PowerShellの出力ストリームとログ設計の知識マップ(知識グラフ)
type: Dataset
description: PowerShellには成功・エラー・警告・詳細・デバッグ・情報の6つの出力ストリームがあり、後続の処理へ渡るのは成功ストリームだけである。Write-Hostは情報ストリームに書き込むため6番でのリダイレクトや捕捉はできるが、既定で常に画面へ表示され続けるため、値を返す用途である成功ストリームの代わりには推奨されない。関数は内部で出力したすべてのオブジェクトを成功ストリームへ返すため、戻り値のあるコマンドを呼び捨てにすると関数の戻り値が汚れ、この問題は$null=…による出力の抑止で軽減できる。Write-VerboseやWrite-Warningなどは[CmdletBinding()]を付けた関数で共通パラメーターにより呼び出し側から表示・捕捉を制御でき、運用として記録したい出来事はWrite-Informationと構造化ログに、進捗表示はデータストリームではなくログに残せないためWrite-Progressと分けて扱う。

PowerShellの出力ストリーム
type: Concept
definition: PowerShellが持つ成功・エラー・警告・詳細・デバッグ・情報の6種類の出力の通り道の総称で、それぞれ番号でリダイレクトできる。
alternative label: Output Streams
alternative label: 成功・エラー・警告・詳細・デバッグ・情報ストリーム

Write-Host
type: Concept
definition: PowerShell 5.0以降はWrite-Informationのラッパーとして情報ストリームへ出力するコマンドレットで、$InformationPreferenceや-InformationActionの影響を受けず(唯一の例外は-InformationAction Ignore)既定でも常に画面に表示される。
alternative label: ホストへの表示
not recommended for: 成功ストリーム

Write-Output
type: Concept
definition: オブジェクトを成功ストリーム(パイプライン)へ送るコマンドレットで、明示的に呼ばなくても式の結果は同じように出力される。
alternative label: 裸の出力
uses: 成功ストリーム

成功ストリーム
type: Concept
definition: 6つの出力ストリームのうち、後続のパイプラインや変数代入へ渡る唯一のストリーム(1番)で、Write-Outputまたは裸の出力がここに書き込む。
alternative label: Success Stream
alternative label: ストリーム1
alternative label: パイプライン出力

Write-Verbose
type: Concept
definition: 詳細(4番)ストリームへメッセージを書き込むコマンドレットで、既定では表示されず呼び出し側が-Verboseを指定したときだけ表示される。
alternative label: 詳細ストリームへの書き込み
uses: PowerShellの出力ストリーム
configured by: 共通パラメーター

Write-Debug
type: Concept
definition: デバッグ(5番)ストリームへメッセージを書き込むコマンドレットで、既定では表示されず呼び出し側が-Debugを指定したときだけ表示される。
alternative label: デバッグストリームへの書き込み
uses: PowerShellの出力ストリーム
configured by: 共通パラメーター

Write-Warning
type: Concept
definition: 警告(3番)ストリームへメッセージを書き込むコマンドレットで、既定で表示され、-WarningActionや-WarningVariableで呼び出し側から制御・捕捉できる。
alternative label: 警告ストリームへの書き込み
uses: PowerShellの出力ストリーム
configured by: 共通パラメーター

Write-Information
type: Concept
definition: 情報(6番)ストリームへ明示的に書き込むコマンドレットで、-Tagsによる分類ができ、既定では表示されないが-InformationVariableなどで捕捉できる。
alternative label: 情報ストリームへの明示的な書き込み
uses: PowerShellの出力ストリーム
configured by: 共通パラメーター
recommended for: 構造化ログ(structured log)

Write-Error
type: Concept
definition: エラー(2番)ストリームへErrorRecordを書き込むコマンドレットで、-ErrorActionや-ErrorVariableで呼び出し側から制御・捕捉できる。
alternative label: エラーストリームへの書き込み
uses: PowerShellの出力ストリーム
configured by: 共通パラメーター

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

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

関数の戻り値の汚染
type: Concept
definition: PowerShellの関数はreturnの有無にかかわらず内部で出力されたすべてのオブジェクトを返すため、戻り値のあるコマンドやメソッドを呼び捨てにするとその値が関数の戻り値に混ざってしまう現象。
alternative label: 戻り値への意図しない出力の混入

$null=…による出力の抑止
type: Concept
definition: 不要な戻り値を$null = ...への代入で捨てる書き方で、Out-Nullへのパイプや[void]キャストより軽量な抑止手段とされる。
alternative label: Null Assignment Suppression
alternative label: Out-Nullによる抑止
mitigates: 関数の戻り値の汚染

構造化ログ(structured log)
type: Concept
definition: 文章ではなくkey=valueのように項目を決めて出力し、あとで機械的に集計できるログの形式。
alternative label: Structured Logging

Write-Progress
type: Concept
definition: コマンドの進行状況をホストの進捗表示として出すコマンドレットで、リダイレクト可能なデータストリームではなく、ログには残せない。
alternative label: 進捗表示
not recommended for: 構造化ログ(structured log)

Start-Transcript
type: Concept
definition: セッションのコマンドとコンソール出力をまるごとテキストファイルに記録するコマンドレットで、Stop-Transcriptで停止する。
alternative label: トランスクリプト記録
uses: PowerShellの出力ストリーム

subject: Write-Output
predicate: uses
object: 成功ストリーム
description: Write-Output(または裸の出力)は成功ストリームへオブジェクトを送り込み、これだけが後続のパイプラインや変数代入へ渡る
evidence: write-output
verified at: 2026-08-01
certainty: established

subject: Write-Host
predicate: notRecommendedFor
object: 成功ストリーム
description: Write-Hostは情報ストリームへの表示専用で、成功ストリーム経由で値をパイプラインへ渡す用途には使えない
evidence: write-host
verified at: 2026-08-01
certainty: established

subject: Write-Host
predicate: uses
object: PowerShellの出力ストリーム
description: PowerShell 5.0以降のWrite-HostはWrite-Informationのラッパーとして情報ストリーム(6番)への書き込みで実装されており、6>や-InformationVariableで捕捉できる
evidence: write-host
verified at: 2026-08-01
certainty: context-dependent

subject: Write-Verbose
predicate: uses
object: PowerShellの出力ストリーム
description: Write-Verboseは詳細(4番)ストリームへ書き込む
evidence: write-verbose
verified at: 2026-08-01
certainty: established

subject: Write-Debug
predicate: uses
object: PowerShellの出力ストリーム
description: Write-Debugはデバッグ(5番)ストリームへ書き込む
evidence: write-debug
verified at: 2026-08-01
certainty: established

subject: Write-Warning
predicate: uses
object: PowerShellの出力ストリーム
description: Write-Warningは警告(3番)ストリームへ書き込む
evidence: write-warning
verified at: 2026-08-01
certainty: established

subject: Write-Information
predicate: uses
object: PowerShellの出力ストリーム
description: Write-Informationは情報(6番)ストリームへ書き込む
evidence: write-information
verified at: 2026-08-01
certainty: established

subject: Write-Error
predicate: uses
object: PowerShellの出力ストリーム
description: Write-Errorはエラー(2番)ストリームへ書き込む
evidence: write-error
verified at: 2026-08-01
certainty: established

subject: Write-Verbose
predicate: requires
object: [CmdletBinding()]属性
description: Write-Verboseの表示を呼び出し側が-Verboseで切り替えられるようにするには、それを使う関数に[CmdletBinding()]を付ける必要がある
evidence: about functions cmdletbindingattribute
verified at: 2026-08-01
certainty: context-dependent

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

subject: Write-Warning
predicate: configuredBy
object: 共通パラメーター
description: Write-Warningの表示可否は共通パラメーターの-WarningActionで呼び出し側から構成できる
evidence: about commonparameters
verified at: 2026-08-01
certainty: established

subject: Write-Verbose
predicate: configuredBy
object: 共通パラメーター
description: Write-Verboseの表示可否は共通パラメーターの-Verboseで呼び出し側から構成できる
evidence: about commonparameters
verified at: 2026-08-01
certainty: established

subject: Write-Debug
predicate: configuredBy
object: 共通パラメーター
description: Write-Debugの表示可否は共通パラメーターの-Debugで呼び出し側から構成できる
evidence: about commonparameters
verified at: 2026-08-01
certainty: established

subject: Write-Information
predicate: configuredBy
object: 共通パラメーター
description: Write-Informationは共通パラメーターの-InformationActionや-InformationVariableで制御・捕捉できる
evidence: about commonparameters
verified at: 2026-08-01
certainty: established

subject: Write-Error
predicate: configuredBy
object: 共通パラメーター
description: Write-Errorは共通パラメーターの-ErrorActionや-ErrorVariableで制御・捕捉できる
evidence: about commonparameters
verified at: 2026-08-01
certainty: established

subject: 成功ストリーム
predicate: mayCause
object: 関数の戻り値の汚染
description: New-Itemなど戻り値を持つコマンドを呼び捨てにすると、その戻り値が成功ストリームに流れ込み関数の戻り値に混ざる
evidence: about return
verified at: 2026-08-01
certainty: context-dependent

subject: $null=…による出力の抑止
predicate: mitigates
object: 関数の戻り値の汚染
description: 不要な出力を$null = ...で捨てることで、関数の戻り値への意図しない混入を防げる
evidence: about return
verified at: 2026-08-01
certainty: established

subject: Write-Information
predicate: recommendedFor
object: 構造化ログ(structured log)
description: 運用として記録したい出来事は、Write-Informationで捕捉できる情報を構造化ログ(1行1JSON)として残すことが本記事の推奨である
evidence: write-information
verified at: 2026-08-01
certainty: established

subject: Write-Progress
predicate: notRecommendedFor
object: 構造化ログ(structured log)
description: Write-Progressの進捗表示はホストの表示機能でありリダイレクト可能なデータストリームではないため、構造化ログの記録手段には向かない。1つのスクリプトが対話的な進捗表示にWrite-Progressを使いながら、別途Write-Informationなどで構造化ログを書くことは問題なくできる。
evidence: write-progress
verified at: 2026-08-01
certainty: established

subject: Start-Transcript
predicate: uses
object: PowerShellの出力ストリーム
description: Start-Transcriptはセッションのコマンドと画面出力(ストリームの表示結果)をまるごとテキストに記録する
evidence: start-transcript
verified at: 2026-08-01
certainty: established