PowerShell でファイルに書き込む：「Out-File」とファイル出力のテクニック

PowerShell における出力の概要

PowerShell に慣れている人なら、PowerShell コマンドの出力は通常、デフォルトでターミナルに表示されることを知っているでしょう。しかし、出力をファイルにリダイレクトしたり保存したりしたい場面もあります。

• コマンドによっては、リアルタイムで扱うのが難しい大量のデータが返されることがあります。このデータをリダイレクトまたは保存すれば、自分の都合のよいタイミングで処理したり確認したりできます。
• あるコマンドの結果を別のプロセスやスクリプトで使うには、PowerShell の出力をファイルに書き出すコマンドを使用して、出力をファイルまたは変数に保存すると、簡単に再利用できます。
• スケジュールされたジョブやその他の自動化タスクは、通常バックグラウンドで実行されます。リアルタイムで出力を確認できない場合があるため、保存しておけばあとで確認できます。
• 場合によっては、出力に必要以上の情報が含まれることがあります。したがって、出力をリダイレクトしたり保存したりして、フィルタリングして整形できます。
• リモートシステムでコマンドを実行する場合、リアルタイムの出力を確認するためにコンソールにアクセスできないことがあります。保存またはリダイレクトを行うと、リモートシステムで何が起きたかの記録を残せます。
• 組織は、システムの状態、設定、またはパフォーマンス指標に基づいてレポートを作成します。PowerShell を使えば、システムデータを問い合わせてレポートを生成し、将来の確認のためにファイルへ出力できます。
• PowerShell は、資産管理やコンプライアンスのためにハードウェアおよびソフトウェアの棚卸し情報を収集するのに使用できます。その後、このデータをファイルに出力して、可視性を高め、管理を簡素化できます。
• タスクを自動化する場合、実行した操作とその結果を追跡することが不可欠です。出力をファイルにリダイレクトすると、監査のためのログを作成しやすくなります。
• スクリプトが失敗した場合は、根本原因を把握する必要があります。出力を保存しておけば、後から見直してエラー処理、デバッグ、トラブルシューティングに活用できます。

要するに、PowerShell の出力をリダイレクトしたり保存したりすると、生産性が向上し、デバッグがしやすくなり、有用なログが得られ、自動化も促進されます。特に、複雑なワークフローや大規模なデータセットを扱う場合に有効です。

PowerShell の結果をファイルに出力するための基本的な方法

Out-File コマンドレット

PowerShell でテキストファイルに書き込む方法では、Out-File cmdlet を使って、コマンド結果（出力）をファイルに直接送るのが一般的です。最もシンプルな形では、Out-File に、出力を書き込むパスとファイル名を指定する必要があります。

既定では、指定したパスに同じ名前のファイルが既に存在する場合はそのファイルを上書きし、存在しない場合は新しいファイルを作成します。

Out-File の構文

Out-File cmdlet の基本的な構文は次のとおりです：

      Out-File
[-FilePath] <cadena>
[[-Encoding] <Encoding>]
[-Append]
[-Force]
[-NoClobber]
[-Width <int>]
[-NoNewline]
[-InputObject <psobject>]
[-WhatIf]
[-Confirmar]
[<CommonParameters>]
      

パラメーター

PowerShell の Out-File cmdlet は、次のパラメーターを受け付けます：

ユースケース

画面に表示するのではなく、出力を直接ファイルに書き込むには、PowerShell の write output to file の方法を使い、Out-File cmdlet を PowerShell のコマンドまたは変数に追加します。この手法は、文字列に対して Out-File を直接追加することで、その文字列をファイルに書き込む場合にも機能します。

PowerShell cmdlet に Out-File を追加する

実行中のプロセスの一覧を取得し、PowerShell の save output to file メソッドを使うには、次の例のように、出力を C:\Temp フォルダー内の “Processes” という名前のテキストファイルに保存します：

Get-Process | Out-File -FilePath C:\Temp\processes.txt

ここでは、Get-Process コマンドレットが実行中のすべてのプロセスを一覧表示します。PowerShell のパイプ出力をファイルに保存する機能を使えば、コマンドの出力結果をすぐにテキストファイルへ保存して、後で分析できます。

Out-File をテキスト文字列に追加する

たとえば、C:\Temp の場所にある「Test」という名前のテキストファイルへ「Hello, World!」を追加するように、PowerShell の「文字列をファイルに書き込む」メソッドを使って文字列を書き込むには、次のコマンドレットを使用します:

"Hello, World!" | Out-File -FilePath C:\Temp\Test.txt

ファイルが存在しない場合は作成されます。存在する場合は、デフォルトで内容が上書きされます。

変数に Out-File を追加する

変数と一緒に Out-File コマンドレットを使用することもできます。たとえば：

$variable | Out-File -FilePath "C:\path\to\file.txt"

ここで $variable は、ファイルに送信したいデータ（例：テキスト ファイルに出力する PowerShell の出力、またはコマンド出力）を保持する変数です。

リダイレクト演算子（> および >>）

PowerShell のリダイレクト演算子（> および >>）は、Out-File cmdlet のシンプルで素早い代替手段であり、出力をファイルにリダイレクトできます。

• > 演算子は、追加のパラメーターなしの Out-File cmdlet と同等です。ファイルが存在する場合は上書きし、存在しない場合は新規に作成します。
• >> 演算子は Out-File -Append と同等です。ファイルが存在する場合は出力を末尾に追記し、存在しない場合は新規に作成します。

これらの演算子には、エラー出力や詳細出力ストリームをリダイレクトするなど、他にも用途がありますが、これはこの記事の範囲外です。

基本構文

演算子を使用するための基本構文は次のとおりです:

<Command> > <Path> # 上書き

<Command> >> <Path> # 追加

リダイレクト演算子はパラメータを使用しないことに注意してください。

例 1 – > 演算子の使用

この cmdlet は、Get-Process の出力を Processes.txt ファイルに書き込みます。宛先に同名のファイルが既に存在する場合は、その既存コンテンツを上書きします。

Get-Process > C:\Temp\Processes.txt

例 2 – >> 演算子の使用

この cmdlet は、既存のコンテンツを上書きせずに、現在の日時を log.txt ファイルの末尾に追記します。

Get-Date >> C:\Temp\log.txt

指定したパスに log.txt というファイルが存在しない場合は、ファイルを作成し、現在の日付と時刻を書き込みます。

Out-File Cmdlet とリダイレクト演算子（> と >>）の違い

Out-File cmdlet とリダイレクト演算子の両方が、PowerShell の出力をファイルに書き込み、さらに追記することができます。両者の主な違いは以下で説明します。

それぞれを使用するタイミング

それに比べて、Out-File cmdlet はより柔軟で、エンコーディング、幅（Width）、上書き制御のオプションが用意されているため、複雑なスクリプトに最適です。一方で、リダイレクト演算子は、カスタマイズが不要な素早い出力作業に対して高速かつ便利です。以下に、それぞれをいつ使用すべきかの簡単なガイドを示します。

Out-File cmdlet を使用するタイミング

• 特定のエンコーディングを指定する場合（例：ASCII、UTF8、Unicode）
• 既存ファイルを上書きしないため（-NoClobber を使用）
• 出力の行幅を制御したい場合（-Width を使用）
• 他の出力制御オプションを維持しながら、追加（append）モードで動作

> と >> はいつ使うべきか

• 追加のフォーマットやエンコードなしで、出力を素早くリダイレクトしたいとき
• 既存のファイルを上書き（>）または追記（>>）したい場合

高度なファイル出力テクニック

上書きの管理

既定では、Out-File コマンドレットは、指定したパスに同名のファイルが存在する場合はそれを上書きし、存在しない場合は新しいファイルを作成します。

既存ファイルを上書きしないようにするには、PowerShell のファイルへの書き込み（追記）メソッドを次の 2 通りの方法のいずれかで使用できます。

• 既存ファイルに出力を追加（追記）する
• 上書きを防止し、その結果、既存ファイルは上書きされず、出力もファイルに保存されません。

出力を追加

Out-File cmdlet と一緒に -Append パラメーターを使用すると、指定したファイルの既存コンテンツを上書きせずに、新しい出力をその末尾に追加できます。たとえば、以前のデータを失うことなくイベントを段階的にログに記録したい場合に特に便利です。

このコマンドは、System ログから最新の 5 件のエントリを event_log.txt ファイルに追加します。

Get-EventLog -LogName System -Newest 5 | Out-File -FilePath C:\Temp\event_log.txt -Append

既存のファイルに出力を追記するには、リダイレクト演算子 >> も使用できます。次の例では、ローカル マシン上のサービスの状態と詳細が、log.txt ファイルの内容に追記されます。

Get-Service >> C:\Temp\log.txt

上書きを防止

Out-File コマンドレットで -NoClobber パラメーターを使用すると、上書きを防止できます。したがって、指定した場所に同名のファイルが既に存在する場合、PowerShell はそれを上書きせず、エラーをスローします。これは重要なファイルを保護するのに役立ちます。

次のコマンドは、Temp フォルダー内に log.txt という名前のファイルを作成しようとします。ただし、この名前のファイルがすでに存在する場合はエラーが表示され、出力はファイルに保存されません。

Get-Service | Out-File -FilePath C:\Temp\log.txt -NoClobber

強制上書き

ファイルが読み取り専用のため、PowerShell の cmdlet の出力で既存ファイルの内容を上書きできない場合があります。このような状況では、Out-File cmdlet に -Force パラメーターを指定して、読み取り専用ファイルを上書きしてください。

この cmdlet はサービス情報を Services.txt ファイルに書き込みます。Services.txt がすでに存在している場合でも、それが読み取り専用であっても上書きされることを保証します。

Get-Service | Out-File -FilePath C:\Temp\Services.txt -Force

出力の書式設定とエンコーディング

PowerShell の Out-File コマンドレットは、出力の書式設定とエンコーディングをカスタマイズするためのオプションを提供します。

出力の書式設定

Out-File コマンドレットは、出力に複数の列がある場合など、期待どおりに出力を表示できないことがあります。整形されて読みやすい出力にするには、幅を調整するか、Format-Table コマンドレットを使用してください。

例 1 – 幅を設定

Out-File と一緒に -Width パラメーターを使用して、出力ファイルの行幅を指定します（デフォルトは 80 文字です）。

この cmdlet は、行幅を 200 文字に設定しながら、サービス情報を Services.txt ファイルに書き込みます。これにより、折り返し（改行）なしでより広い出力が可能になります。

Get-Service | Out-File -FilePath C:\Temp\Services.txt -Width 200

例 2 – Format-Table でフォーマットする

Out-File cmdlet に送信する前に、Format-Table cmdlet を使用してデータを構造化します。

この cmdlet は、可読性のために Format-Table -AutoSize を使用して列幅を自動的に調整します。

Get-Service | Format-Table -AutoSize | Out-File -FilePath C:\Temp\Services.txt

エンコーディングを設定

Out-File cmdlet を使用する際に PowerShell の出力をエンコードすると、データがさまざまなシステムやアプリケーションで正しく解釈・表示され、互換性も確保されます。

-Encoding パラメーターは、ファイル内で出力テキストがどのようにエンコードされるかを指定するのに役立ちます。よく使われるエンコーディングの種類には次のようなものがあります:

• UTF8 – Web アプリケーションで一般的で、すべての文字をサポートします。
• ASCII – 基本的な英語文字のみに限定されており、コンパクトですが制約があります。
• Unicode (UTF-16) – Windows との互換性に適しており、多種多様な特殊文字、記号、国際的なテキストを扱えますが、より多くの領域を使用します。
• Default – システムのデフォルトのエンコーディングを使用します。環境によって変わる可能性があり、プラットフォーム間で予測しにくいことがあります。

例 1 — UTF-8 エンコーディングを使用する

出力ファイルに特殊文字が含まれている場合、または UTF-8 が標準の文字コードとして使用される環境でファイルを利用する場合は、UTF-8 エンコーディングを使用するのがよいでしょう。

この cmdlet は、システム上のサービス一覧を取得し、ファイルのエンコーディングを UTF-8 に設定したうえで、その情報を Services.txt ファイルに出力します。

Get-Service | Out-File -FilePath C:\Temp\Services.txt -Encoding UTF8

例 2 — ASCII エンコーディングを使用する

ASCII エンコーディングは、よりシンプルなテキストファイルによく使用されます。

この cmdlet は、システム上のサービスの一覧を取得し、出力を Services.txt ファイルにパイプします。-Encoding パラメーターは、出力を ASCII 形式に変換するために使用されます。

Get-Service | Out-File -FilePath C:\Temp\Services.txt -Encoding ASCII

特定の出力ストリームの取り扱い

Out-File の cmdlet は、コマンドまたはスクリプトの成功した結果をファイルに書き込みます。しかし、エラー、警告、または特定の種類のメッセージはファイルに書き込みません。これはリダイレクト演算子で実現でき、どのストリームをファイルに出力するかを指定できます。

例 1 — エラーメッセージをファイルに送信

このコマンドは、Readme という名前のファイルを一覧表示（ls）しようとします。パスを指定しない場合は、現在のディレクトリ内でそのファイルを探します。ファイルが存在しない場合は、エラーメッセージが生成されます。2> 演算子により、このエラーは error.log というファイルにリダイレクトされます。その結果、エラーは画面に表示されず、Temp フォルダー内の error.log に保存されます。

ls Readme 2> C:\Temp\error.log

例 2 — 警告をファイルに送信する

PowerShell では、警告ストリームはストリーム番号 3 です。3> を使って警告をファイルにリダイレクトできます。例は次のとおりです：

# 警告を生成するコマンド

<Your-Command> 3> C:\Temp\warning_log.txt

出力の代替方法

Set-Content および Add-Content の Cmdlet

Set-Content および Add-Content の cmdlet は、出力をファイルに書き込む別の方法です。

• Set-Content は、指定した新しいコンテンツでファイル内の既存のコンテンツを上書きします。ファイルが存在しない場合は、それを作成します。
• Add-Content は、既存のファイル内容の末尾に新しいコンテンツを追加します。ファイルが存在しない場合は作成しますが、既存のコンテンツは置き換えません。

Set-Content の cmdlet

Set-Content の cmdlet を使用して、ファイルの内容を書き込み、または新しいコンテンツで置き換えます。

この cmdlet は、Test.txt ファイル内の既存のコンテンツを上書きします。-Value パラメーターは、既存のコンテンツに代わって置き換えるコンテンツまたはテキストを指定します。

Set-Content -Path C:\Temp\Test.txt -Value "ここにコンテンツを追加"

Add-Content cmdlet

Add-Content cmdlet を使用すると、ファイルにコンテンツを追加できます。つまり、既存のファイルを上書きせずに、そのファイルに新しいデータを追記できます。Add-Content は、複数のファイルに対して一度にコンテンツを追記することも可能です。

Out-File cmdlet やリダイレクト演算子と同様に、同じ名前のファイルが存在しない場合、Add-Content cmdlet は新しいファイルを作成します。

例 1 — ファイルにテキストを追記する

この cmdlet は Test.txt ファイルに新しいテキストを追加します。-Value パラメーターは、ファイルに追記したい内容またはテキストを指定します。

Add-Content -Path C:\Temp\Test.txt -Value "追加する新しい行"

ファイルが読み取り専用の場合、内容を追加できるようにするには -Force パラメーターを使用する必要があります。

例 2 — 複数のファイルにテキストを追記する

複数のファイルに同じ内容を追加するには、いくつかの方法があります。

• パス内でワイルドカードを使用して、更新したいファイルを指定します
• 更新したくないファイル名を除外します

この cmdlet は、ファイル名に test が含まれるファイルを除き、Temp フォルダー内のすべての .txt ファイルに現在の日付を追加します：

Add-Content -Path C:\Temp\files\*.txt -Value (Get-Date) -Exclude "test*"

例 3 — 複数行のテキストを追加

このコマンドは、Test.txt ファイルに複数行のテキストを追加します。

      $lines = @(
"Line 1: Details",
"Line 2: Specific Details"
)
Add-Content -Path C:\Temp\Test.txt -Value $lines
      

.NET クラス

.NET クラスを使って、ファイルへの出力を生成できます。特に、大量データの取り扱いを伴う高度なシナリオでは有用です。これらのクラスは次のとおりです。

• BinaryWriter – 基本データ型をバイナリ形式でストリームに書き込みます。
• StreamWriter – 特定のエンコーディングでストリームに文字を書き込むために使用します。テキストファイルの作成や変更によく用いられます。
• StringWriter – は文字列に情報を書き込みます。このクラスでは、PowerShell が文字列情報を StringBuilder オブジェクトに保存します。

C#で StreamWriter クラスを使用して出力をファイルに送るのは簡単です。次の例は、その使い方を示しています。

      # Get the directories in C:\
$Dirs = Get-ChildItem -Path C:\ -Directory
# Open a stream writer
$File = 'C:\Temp\Dirs.txt'
$Stream = [System.IO.StreamWriter]::new($File)
# Write the folder names for these folders to the file
foreach($Dir in $Dirs) {
$Stream.WriteLine($Dir.FullName)
}
# Close the stream
$Stream.Close()
      

このスクリプトは、C:\ ドライブ上のディレクトリを一覧表示し、それらのパスをテキストファイルに保存するために、次の手順を実行します:

ステップ1:

$Dirs = Get-ChildItem -Path C:\ -Directory

この行では、-Directory パラメーター付きの Get-ChildItem を使用して、C:\ ドライブ内のディレクトリ（ファイルではありません）のみを取得します。結果は、ディレクトリ オブジェクトのリストとして $Dirs 変数に保存されます。

ステップ 2:

$File = 'C:\Temp\Dirs.txt'

$Stream = [System.IO.StreamWriter]::new($File)

これらの行では、ディレクトリのリストを保存するファイル パス（C:\Temp\Dirs.txt）を用意し、その後、そのファイルへ書き込むための StreamWriter オブジェクトを初期化します。このオブジェクトは $Stream に割り当てられます。

ステップ 3：

foreach($Dir in $Dirs) {

$Stream.WriteLine($Dir.FullName)

}

このループは、$Dirs 内の各ディレクトリ オブジェクトを順に処理します。各ディレクトリについて、$Stream.WriteLine を使用して完全パス（$Dir.FullName）をファイルに書き込みます。

ステップ 4：

$Stream.Close()

すべてのディレクトリ パスを書き込んだ後、スクリプトは StreamWriter を閉じます。

PowerShell のファイル出力に関するベストプラクティス

適切な行幅を設定して切り捨てを防ぎます

PowerShell では -Width パラメーターで適切な行幅を設定して、長い行が切り捨てられないようにし、ファイル出力が意図した形式で整形されるようにしてください。

Out-File コマンドレットの -Width パラメーターは、出力の 1 行あたりの最大文字数を制御します。既定では 80 文字に設定されており、より長い行は切り捨てられる可能性があります。たとえば、下記のように幅を 200 文字に増やせます:

Get-Process | Out-File -FilePath "output.txt" -Width 200

次の点を確認してください:

• 不要な空白や切り捨て（truncation）を避けるために、最長の行に合わせて -Width を設定してください。ほとんどの出力では、120〜200 文字の幅でうまく機能します。
• 列数が多いデータ（CSV ファイルなど）では、行全体を収められるように、より大きな幅を設定してください。
• パイプラインでは Out-String -Width を使って行の幅を制御し、Out-File に渡す前に、行全体が指定した幅に収まることを確認します。

適切なエンコーディングを設定する

PowerShell が使用する既定のエンコーディングは、使用している cmdlet と PowerShell のバージョンによって異なります。次の表は、使用される既定のエンコーディングを示しています。

システム間の互換性のために UTF-8 エンコーディングが推奨されます。ただしレガシーシステムの場合は、-Encoding ASCII または -Encoding Unicode を指定したいことがあります。

すべてのスクリプトにわたって既定値を設定するには $PSDefaultParameterValues を使用します

PowerShell の $PSDefaultParameterValues を使用すると、スクリプトやセッション全体でパラメーターの既定値を設定できます。オプションを繰り返し指定しなくても一貫性を強制する方法を提供します。

Out-File に対して UTF8 エンコーディングとより広い幅を使用するように、グローバルの既定値を設定する方法は次のとおりです。

$PSDefaultParameterValues["Out-File:Encoding"] = "UTF8"

$PSDefaultParameterValues["Out-File:Width"] = 200

Out-File を Format-Table や Format-List と組み合わせて、より構造化された出力にする

Out-File の cmdlet を Format-Table または Format-List と組み合わせると、構造化されていて読みやすいテキスト出力ファイルを作成できます。

Format-Table

Format-Table は、行と列の構造が明確なデータに最適です。整理された、読みやすい表のような形式を作成します。ただし、Out-File の cmdlet と一緒に使う場合は、次の点を考慮してください：

• 必要な列だけを指定するには、-Property パラメーターを使用します。これにより、出力ファイルが煩雑になるのを防げます。
• 列幅をコンテンツに合わせて最適化するには、-AutoSize パラメーターを使用します。これにより、余分な空白や切り捨て(トランケーション)を減らせます。
• 切り捨て(トランケーション)を防ぎ、出力の整列を維持するには、-Width パラメーターを使用します。

例を示します：

Get-Process | Format-Table -Property Name, ID, CPU, WS -AutoSize | Out-File -FilePath "ProcessList.txt" -Width 200

Format-List

Format-List はデータを縦方向に表示し、1 行につき 1 つのプロパティを表示します。プロパティが多い場合や、値が長いフィールドがある場合は、そうした値が途中で切り捨てられないようにするために、この形式を使用してください。この形式はレポートや詳細なログに適しています。

Format-List と Out-File を併用する例はこちらです:

Get-Process | Format-List -Property Name, ID, CPU, StartTime | Out-File -FilePath "DetailedProcessList.txt"

Format-Table と同様に、必要なプロパティだけを選択してください。

Test-Path を使って、書き込み前にファイルが存在するか確認することでファイル競合を防止します

ファイルに書き込む前に、そのファイルが存在するかどうかを確認するのは常に賢明です。こうすることで、誤って上書きしてしまうことを避け、既にファイルが存在する場合にどうするかを判断できます。PowerShell の Test-Path コマンドレットを使うと、ファイルの存在を確認できます。

以下の手順に従ってください：

1. ファイル パスを変数に割り当てます。
2. Test-Path コマンドレットを使用して、ファイルが存在するかどうかを確認します。
3. 追加（append）、上書き（overwrite）、リネーム（rename）、または書き込みをスキップするかを決めてください。
4. Out-File cmdlet を使用して、ファイルを作成するか、ファイルに書き込みます。

よくある落とし穴と解決策

PowerShell の Out-File cmdlet は、ファイルの取り扱い、エンコード、内容の追記（appending content）などの点で、時にはよくある落とし穴につながることがあります。以下では、よくある問題とその解決策をいくつか紹介します。

上書きによるデータ損失を防ぐ

既定では、同じ名前のファイルが既に存在する場合、Out-File コマンドレットは警告なしに既存ファイルの内容を上書きします。これを回避する方法はいくつかあります：

• -Append パラメーターを使用して、既存ファイルを上書きするのではなく出力を追加します。
• Test-Path でファイルが存在するか確認し、Out-File をどのように進めるかを決めます。

不適切なエンコーディングによるデータ損失を防ぐ

既定では、Out-File は PowerShell 5.1 およびそれ以前のバージョンでは Unicode エンコーディングを使用します。PowerShell Core およびそれ以降のバージョンでは UTF-8 エンコーディングを使用します。

既定のエンコーディングは、お使いのシステムや別のエンコーディングを想定しているアプリケーションと互換性がない場合があります。そのため、-Encoding パラメーターを使用してエンコーディングを明示的に指定する必要があります。

長時間実行するスクリプトでは、パフォーマンスを確保するために出力を管理してください

PowerShell ISE のような制約のある環境では、Out-File cmdlet を使ってスクリプトを実行すると、次のような問題が発生する可能性があります。

• 複雑なデータ構造を想定どおりに処理できない
• 長い出力が切り詰められる（トランケーションされる）

長い出力を管理するには、次の方法を使えます:

• 適切な幅を設定するには -Width パラメーターを使用します
• Export-Csv または ConvertTo-Json の cmdlet を使って、複雑なデータを CSV や JSON などの構造化形式にエクスポートします

PowerShell スクリプトではログ記録とエラー処理を適切に行います

場合によっては、ファイルが使用中だったり、別のプロセスによってロックされていることがあります。この場合、Out-File cmdlet は書き込めないためエラーをスローします。こうしたエラーやその他のエラーは、try/catch ブロックで処理できます。例は次のとおりです:

      $content = "Write content to file"
$filePath = "C:\Temp\Errors.txt"
try {
$content | Out-File -FilePath $filePath
Write-Host "File written successfully."
} catch {
Write-Host "File is in use or locked by another process."
}