Windows PowerShell: The Many Options for Out
There are more ways to generate output using Windows PowerShell than you may think. Here are some that have recently come to light.
Windows PowerShell is one of those neat products where I’m constantly discovering new features and capabilities. Generating output—getting information onto the screen or into some other format—is one area where Windows PowerShell shows its remarkable depth and versatility.
Open up a copy of Windows PowerShell (preferably v2, available as a download for versions of Windows back to Windows XP) and run Gcm –verb Out. You’ll see a list of all the cmdlets designed to create output in various forms.
How Output Happens
Like everything in Windows PowerShell, the various Out- cmdlets are designed to consume objects. That means you display output on the screen—called the host window—by running a command like this:
Get-Process | Out-Host
In reality, the Out-Host portion of that is unnecessary, because Windows PowerShell has the Out-Default cmdlet hardcoded into the end of the pipeline. That cmdlet simply forwards things to Out-Host. So this command:
Is functionally the same as:
Get-Process | Out-Default
Out-Default will internally forward objects to Out-Host. What’s interesting about all the Out- cmdlets is that they can’t actually process “real” objects. The Out- cmdlets can only handle a special type of formatting object produced by the shell’s formatting subsystem.
When an Out- cmdlet receives “normal” objects, it internally calls one of the Format- cmdlets based on a set of internal rules and configuration defaults. The Format- cmdlet produces formatting objects that describe how to construct output, and the Out- cmdlet puts that output into the specified device. So running this:
Is really a lot like running this:
Get-Process | Format-Table | Out-Host
The lesson here is that the Out- cmdlets can only use what’s produced by a Format- cmdlet. For the most part, only an Out- cmdlet can handle what the Format- cmdlets produce. So a Format- cmdlet will always be the last thing on your command line, with the sole exception of when it’s followed by an Out- cmdlet.
Out: End of the Line
Because Out- cmdlets are supposed to deal with the final result of whatever command you’ve run, they themselves (with one exception) don’t produce any output. If you’re using an Out- cmdlet, it will always be the very last thing on your command line. After the Out- cmdlet runs, there won’t be anything in the pipeline for additional cmdlets to act upon.
The sole exception to this rule, at least with the built-in Out- cmdlets, is Out-String. It behaves much differently than normal Out- cmdlets. It places String objects into the pipeline. That cmdlet and its exceptions are not the focus here, but be aware that they exist. Run Help Out-String if you’d like to learn more.
Wait—did I say “built-in Out- cmdlets?” Indeed, and the implication that there are other Out- cmdlets is absolutely true. For example, there’s a third-party commercial add-in called PowerGadgets. This adds fun cmdlets like Out-Chart and Out-Gauge to your shell’s repertoire. Add-in Out- cmdlets might not exhibit all of the same rules and behavior outlined here, so be sure to read their help pages (if provided) to better understand how they work and what they do.
Options for Out
Windows PowerShell comes with numerous built-in output options:
- Out-Host is the default when you don’t specify anything else
- Out-Printer sends output to a printer. This output is formatted, either by whatever Format- cmdlet you used or by the defaults in the formatting subsystem
- Out-File sends output to a file. This is functionally the same as running something like Dir > file.txt. The > and >> shortcuts are actually using Out-File under the hood. Out-File has tons of options for setting the output file width (which affects formatting decisions made by the shell), character encoding, appending or overwriting, and so on
- Out-Grid is new in Windows PowerShell v2 and requires the Microsoft .NET Framework 3.5 SP1 to work properly. This displays your objects in a graphical table with click-to-sort column headers and a search/filter box to help locate specific results
Reading the help for these cmdlets can be extremely educational. For example, did you know Out-Host has a –paging parameter that causes it to display one page of output at a time? This is similar to the “more” command in the old Cmd.exe shell. Try running this:
Get-Service | Out-Host –paging
The –width parameter of Out-File is useful for creating exceptionally wide tables. I’ve generated huge tables and printed the resulting files on a plotter to create a nice, wall-mounted display. The default width is only 80 columns, which doesn’t allow for very wide tables. By default, the shell will only display something as a table if it has four or fewer columns, or if a configuration default provides for a custom table layout:
Get-WmiObject Win32_Service | Format-Table * | Out-File c:\services.txt –width 750
Out-Printer provides a –name parameter so you can specify the printer you want. It’ll use your Windows default printer if you don’t specify another.
Finally, Out-Grid also lets you specify a title for the display window, using the cmdlet’s –title parameter. That’s useful when a script displays a grid to a user, because a good title can help them understand what they’re seeing.
When Output Isn’t
Finally, there’s Out-Null. This cmdlet is used to “eat” output you don’t want to see. For example, most Windows Management Instrumentation methods return an object indicating their success or failure. If you don’t want to see that output, simply pipe it to Out-Null:
Invoke-WmiMethod –name reboot –class win32_operatingsystem | Out-Null
Not only is playing with the different output options fun, it gives you a better idea of what Windows PowerShell can do for you. You’ll realize the full extent to which you can work more easily and do less work on your own.