Skip to content
Tutorials Center
My learning

Topics

Lesson 9 of 34 ยท Objects and the Pipeline

Formatting and Output

Control how PowerShell shows and saves objects: Format-Table, Format-List, Out-String, Out-File and Export-Csv, and why formatting must always come last.

Until now the pipeline has passed objects from one command to the next. At the very end, something has to turn those objects into pixels on your screen or bytes in a file. PowerShell does this with a set of formatting and output cmdlets, and the single most important rule is that they belong at the end of the pipeline. Get this right and your scripts stay flexible. Get it wrong and you will meet baffling "garbage" in your CSV files.

This lesson explains what happens when you press Enter on a command with no formatting, how Format-Table and Format-List shape the display, how to turn the display into a string, how to write to files, and how Export-Csv saves real data. It follows filtering and selecting and grouping and measuring, and it is the last stop in this chapter before variables and types.

Real PowerShell cannot run on this page, so its commands are read-only. The runnable examples use a JavaScript stand-in: a small table and list renderer, plus a CSV writer, that show the idea. Real PowerShell chooses columns and widths in more sophisticated ways, so the stand-in output is similar in spirit, not identical.

Objects first, text last

Objects Filter, sort and measure while they are still objects.
Format-* Turn them into a layout for your eyes.
Out-* Send the result to the screen, a file or a string.

Format-* output is for people, not for other commands.

1 / 2

What happens when you do nothing

If you type Get-Process and press Enter, PowerShell quietly appends a call to Out-Default, which picks a default view for the object type and prints it as a table or a list. PowerShell ships with view definitions for common types, and the rule for types without one is simple: four or fewer properties give a table, five or more give a list.

That is why Get-Date | Select-Object * fills a screen and Get-Service prints neat columns. The objects themselves always contain every property; the view only decides what to show.

Format-Table and Format-List

Format-Table (alias ft) arranges properties as columns. Name the properties you want:

POWERSHELL
Get-Process | Format-Table -Property Name, Id, WS
Get-Process | Format-Table Name, Id, WS -AutoSize
  • -AutoSize sizes columns to fit the data (but PowerShell must read all the objects first).
  • -Wrap wraps long cell text instead of cutting it off with ....
  • -GroupBy Status prints a separate table for each value of a property. Sort by that property first, so equal values are adjacent.
  • Columns accept the same kind of hashtable as calculated properties, with extra keys for layout:
POWERSHELL
Get-ChildItem | Format-Table Name,
    @{ Label = 'KB'; Expression = { [math]::Round($_.Length / 1KB, 1) }; Alignment = 'Right'; FormatString = 'N1' }

Format-List (alias fl) prints one property per line, which is better for objects with many properties or long values. Format-List * shows every property, a good way to explore an object:

POWERSHELL
Get-Service -Name Spooler | Format-List -Property *

There are also Format-Wide (one property in several columns, like dir /w) and Format-Custom, rarely needed.

Why formatting must come last

Format cmdlets do not return your objects. They return a different set of internal formatting objects that only the host knows how to draw. Anything after a Format-* command receives those, not your data.

POWERSHELL
# Wrong: the CSV describes formatting records, not processes
Get-Process | Format-Table Name, Id | Export-Csv processes.csv

# Right: export the real objects, with the properties you want
Get-Process | Select-Object Name, Id | Export-Csv processes.csv

The first line writes a file with columns that describe the formatting instructions (they start with names like ClassId2e4f51ef), none of your process names. The same goes for Where-Object, Sort-Object and Measure-Object: use them before formatting, never after.

If your script returns Format-Table output from a function, the caller cannot filter, sort or export it. Return objects from functions, and let the person at the console decide how to format them.

A second surprise: mixing two different object types in one pipeline can make PowerShell print the second type's columns under the first type's header, or print nothing for the second type, because a table is bound to the first object it sees. When output looks odd, pipe to Format-List or format each type separately.

Output cmdlets: where does it go?

The Out-* cmdlets decide the destination:

Cmdlet Destination
Out-Host The console (what happens by default; -Paging pages output)
Out-String Turns the display into a single string (-Stream gives one string per line)
Out-File A text file
Out-Null Throws the output away
Out-GridView A sortable, filterable window (Windows only)

Out-String is how you capture "what I would have seen" as text, for logging or email bodies:

POWERSHELL
$text = Get-Process | Select-Object -First 3 Name, Id | Format-Table | Out-String

By default Out-String returns one multi-line string. Use -Width 200 when long lines must not be cut off, and -Stream when you want to process line by line.

Writing text files

Out-File writes the displayed form of objects to a file, exactly as it would look in the console, including any column cutting at the console width. The redirection operators > and >> are shorthand for Out-File and Out-File -Append.

POWERSHELL
Get-Process | Format-Table Name, Id -AutoSize | Out-File processes.txt -Width 200
'Log started' | Out-File log.txt -Append
Get-Date | Out-File date.txt -Encoding utf8

For plain strings you control yourself, Set-Content and Add-Content are usually the better fit, and Get-Content reads them back (see Working with Files and Folders).

Encoding differs between editions. In Windows PowerShell 5.1, Out-File and > write UTF-16 (labelled "Unicode") by default, Set-Content uses the system's legacy code page, and Export-Csv uses ASCII. PowerShell 7 writes UTF-8 without a byte order mark almost everywhere. If another program must read your file, set -Encoding explicitly.

Saving real data with Export-Csv

To save objects as data rather than as a picture, use Export-Csv. It writes one row per object and one column per property:

POWERSHELL
Get-ChildItem C:\Logs -File |
    Select-Object Name, Length, LastWriteTime |
    Export-Csv -Path logs.csv -NoTypeInformation -Encoding utf8
  • In Windows PowerShell 5.1, Export-Csv writes a first line starting with #TYPE, unless you add -NoTypeInformation. PowerShell 7 does not write that line, and the switch is accepted but unnecessary.
  • -Delimiter ';' changes the separator, -Append adds rows to an existing file.
  • Property values become their text form, so a nested object (like an array) shows up as a type name rather than its contents. Flatten first, for example with a calculated property that uses -join.

Import-Csv reads the file back into objects, but every value is then a string, which matters when you sort or compare numbers. This is covered in CSV, JSON and XML.

Stand-in: a table, a list and a CSV in JavaScript

The first example writes small versions of Format-Table, Format-List and Out-String: each takes plain objects and produces text. Data lives in an array, the property list controls the columns, and right-aligned numbers mimic PowerShell's alignment.

JS Format-Table and Format-List as functions

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Formatting here returns a plain string, just as Out-String hands you the display as text. Real PowerShell is more careful, for example it measures the console width and truncates with an ellipsis, which this stand-in skips.

The second example shows why order matters. toCsv needs objects to find column names. If you give it text from a formatter instead, the only "column" it can find is the text itself, which is the same kind of mistake as Format-Table | Export-Csv in PowerShell (where the junk columns are formatting records rather than a single text column).

JS Export real objects, not formatted text

Press Run (or Ctrl + Enter) to see the console output here.

No output.

In the real shell the wrong version is even stranger, because the formatting objects have their own properties, but the lesson is the same: the data is gone once you format.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does this do: Get-Process | Format-Table Name, Id | Export-Csv p.csv ?

    Format-Table emits formatting objects meant for the host. Export-Csv receives those and writes their properties, so the real process data is lost. Select the properties with Select-Object and export that.
  2. 2. Which cmdlet captures what would be displayed as a single string?

    Out-String converts the display into a string (or one string per line with -Stream). Out-Null discards output, Out-Host writes to the console, and Out-GridView opens a window on Windows.
  3. 3. In Windows PowerShell 5.1, what encoding do Out-File and the > operator use by default?

    Windows PowerShell 5.1 writes UTF-16 from Out-File and >, while PowerShell 7 switched to UTF-8 without a BOM. Pass -Encoding when another program reads the file.
  4. 4. When is Format-List a better choice than Format-Table?

    A list shows one property per line, so wide objects stay readable. It is still only for display, never for passing data on.
  5. 5. Why is Out-File sometimes cutting off table text in the file?

    Out-File writes the display, laid out for a width. Use -Width to widen it, or save data with Export-Csv or Set-Content instead.

Summary

  • Without explicit formatting, Out-Default chooses a table or list view for the object type; the objects still hold all their properties.
  • Format-Table (columns, -AutoSize, -Wrap, -GroupBy) and Format-List (one property per line, * for everything) are for human eyes only.
  • Always put Format-* last: after it, the pipeline carries formatting records, not your data.
  • Out-String captures the display as text, Out-File and > write the display to a file, and Out-Null discards output.
  • Encodings differ: Windows PowerShell 5.1 defaults to UTF-16 for Out-File, PowerShell 7 to UTF-8 without BOM, so set -Encoding when it matters.
  • Save objects as data with Export-Csv (use -NoTypeInformation in 5.1) after selecting the properties you want.

Now step from commands into the language itself with Variables and Types.