Redirecting Data with Out-* Cmdlets

Windows PowerShell provides several cmdlets that let you control data output directly. These cmdlets share two important characteristics.

First, they generally transform data to some form of text. They do this because they output the data to system components that require text input. This means they need to represent the objects as text. Therefore, the text is formatted as you see it in the Windows PowerShell console window.

Second, these cmdlets use the Windows PowerShell verb Out because they send information out from Windows PowerShell to somewhere else. The Out-Host cmdlet is no exception: the host window display is outside of Windows PowerShell. This is important because when data is sent out of Windows PowerShell, it is actually removed. You can see this if you try to create a pipeline that pages data to the host window, and then attempt to format it as a list, as shown here:

PS> Get-Process | Out-Host -Paging | Format-List

You might expect the command to display pages of process information in list format. Instead, it displays the default tabular list:

Handles  NPM(K)    PM(K)      WS(K) VM(M)   CPU(s)     Id ProcessName
-------  ------    -----      ----- -----   ------     -- -----------
    101       5     1076       3316    32     0.05   2888 alg
    618      18    39348      51108   143   211.20    740 explorer
    257       8     9752      16828    79     3.02   2560 explorer
<SPACE> next page; <CR> next line; Q quit

The Out-Host cmdlet sends the data directly to the console, so the Format-List command never receives anything to format.

The correct way to structure this command is to put the Out-Host cmdlet at the end of the pipeline as shown below. This causes the process data to be formatted in a list before being paged and displayed.

PS> Get-Process | Format-List | Out-Host -Paging

Id      : 2888
Handles : 101
CPU     : 0.046875
Name    : alg

Id      : 740
Handles : 612
CPU     : 211.703125
Name    : explorer

Id      : 2560
Handles : 257
CPU     : 3.015625
Name    : explorer
<SPACE> next page; <CR> next line; Q quit

This applies to all of the Out cmdlets. An Out cmdlet should always appear at the end of the pipeline.


All the Out cmdlets render output as text, using the formatting in effect for the console window, including line length limits.

Paging Console Output (Out-Host)

By default, Windows PowerShell sends data to the host window, which is exactly what the Out-Host cmdlet does. The primary use for the Out-Host cmdlet is paging data as we discussed earlier. For example, the following command uses Out-Host to page the output of the Get-Command cmdlet:

PS> Get-Command | Out-Host -Paging

You can also use the more function to page data. In Windows PowerShell, more is a function that calls Out-Host -Paging. The following command demonstrates using the more function to page the output of Get-Command:

PS> Get-Command | more

If you include one or more filenames as arguments to the more function, the function will read the specified files and page their contents to the host:

PS> more c:\boot.ini
[boot loader]
[operating systems]

Discarding Output (Out-Null)

The Out-Null cmdlet is designed to immediately discard any input it receives. This is useful for discarding unnecessary data that you get as a side-effect of running a command. When type the following command, you do not get anything back from the command:

PS> Get-Command | Out-Null

The Out-Null cmdlet does not discard error output. For example, if you enter the following command, a message is displayed informing you that Windows PowerShell does not recognize 'Is-NotACommand':

PS> Get-Command Is-NotACommand | Out-Null
Get-Command : 'Is-NotACommand' is not recognized as a cmdlet, function, operabl
e program, or script file.
At line:1 char:12
+ Get-Command  <<<< Is-NotACommand | Out-Null

Printing Data (Out-Printer)

You can print data by using the Out-Printer cmdlet. The Out-Printer cmdlet will use your default printer if you do not provide a printer name. You can use any Windows-based printer by specifying its display name. There is no need for any kind of printer port mapping or even a real physical printer. For example, if you have the Microsoft Office document imaging tools installed, you can send the data to an image file by typing:

PS> Get-Command Get-Command | Out-Printer -Name "Microsoft Office Document Image Writer"

Saving Data (Out-File)

You can send output to a file instead of the console window by using the Out-File cmdlet. The following command line sends a list of processes to the file C:\temp\processlist.txt:

PS> Get-Process | Out-File -FilePath C:\temp\processlist.txt

The results of using the Out-File cmdlet may not be what you expect if you are used to traditional output redirection. To understand its behavior, you must be aware of the context in which the Out-File cmdlet operates.

By default, the Out-File cmdlet creates a Unicode file. This is the best default in the long run, but it means that tools that expect ASCII files will not work correctly with the default output format. You can change the default output format to ASCII by using the Encoding parameter:

PS> Get-Process | Out-File -FilePath C:\temp\processlist.txt -Encoding ASCII

Out-file formats file contents to look like console output. This causes the output to be truncated just as it is in a console window in most circumstances. For example, if you run the following command:

PS> Get-Command | Out-File -FilePath c:\temp\output.txt

The output will look like this:

CommandType     Name                            Definition                     
-----------     ----                            ----------                     
Cmdlet          Add-Content                     Add-Content [-Path] <String[...
Cmdlet          Add-History                     Add-History [[-InputObject] ...

To get output that does not force line wraps to match the screen width, you can use the Width parameter to specify line width. Because Width is a 32-bit integer parameter, the maximum value it can have is 2147483647. Type the following to set the line width to this maximum value:

Get-Command | Out-File -FilePath c:\temp\output.txt -Width 2147483647

The Out-File cmdlet is most useful when you want to save output as it would have displayed on the console. For finer control over output format, you need more advanced tools. We will look at those in the next chapter, along with some details about object manipulation.