Tutorials  PowerShell Cmdlet Help for Out-String


Sends objects to the host as a series of strings.

Out-String [-InputObject ] [-Stream] [-Width ] []

The Out-String cmdlet converts the objects that Windows PowerShell manages into an array of strings. By default, Ou
t-String accumulates the strings and returns them as a single string, but you can use the stream parameter to direc
t Out-String to return one string at a time. This cmdlet lets you search and manipulate string output as you would
in traditional shells when object manipulation is less convenient.

Specifies the objects to be written to a string. Enter a variable that contains the objects, or type a command
or expression that gets the objects.

Required? false
Position? named
Default value
Accept pipeline input? true (ByValue)
Accept wildcard characters? false

-Stream []
Sends the strings for each object separately. By default, the strings for each object are accumulated and sent
as a single string.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false

Specifies the number of characters in each line of output. Any additional characters are truncated, not wrapped
. If you omit this parameter, the width is determined by the characteristics of the host. The default for the P
owerShell.exe host is 80 (characters).

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false

This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
OutBuffer and OutVariable. For more information, type,
"get-help about_commonparameters".

You can pipe objects to Out-String.

Out-String returns the string that it creates from the input object.


The cmdlets that contain the Out verb (the Out cmdlets) do not format objects; they just render them and send t
hem to the specified display destination. If you send an unformatted object to an Out cmdlet, the cmdlet sends
it to a formatting cmdlet before rendering it.

The Out cmdlets do not have parameters for names or file paths. To send data to an Out cmdlet, use a pipeline o
perator (|) to send the output of a Windows PowerShell command to the cmdlet. You can also store data in a vari
able and use the InputObject parameter to pass the data to the cmdlet. For more information, see the examples.

-------------------------- EXAMPLE 1 --------------------------

C:\PS>get-content C:\test1\testfile2.txt | out-string

This command sends the content of the Testfile2.txt file to the console as a single string. It uses the Get-Content
cmdlet to get the content of the file. The pipeline operator (|) sends the content to Out-String, which sends the
content to the console as a string.

-------------------------- EXAMPLE 2 --------------------------

C:\PS>$c = get-culture | select-object *

C:\PS> out-string -inputobject $c -width 100

These commands get the regional settings for the current user and convert the data to strings. The first command us
es the Get-Culture cmdlet to get the regional settings. The pipeline operator (|) sends the result to the Select-Ob
ject cmdlet, which selects all properties (*) of the culture object that Get-Culture retrieved. The command then st
ores the results in the $c variable.

The second command uses Out-String to convert the CultureInfo object to a series of strings (one string for each pr
operty). It uses the InputObject parameter to pass the $c variable to Out-String. The width parameter is set to 100
characters per line to prevent truncation.

-------------------------- EXAMPLE 3 --------------------------

C:\PS>get-alias | out-string -stream | select-string "Get-Command"

This command displays aliases that include the phrase "Get-Command". It uses the Get-Alias cmdlet to get a set of A
liasInfo objects (one for each alias in the current session). This example demonstrates the difference between work
ing with objects and working with strings.

The pipeline operator (|) sends the output of Get-Alias to Out-String, which converts the objects to a series of st
rings. It uses the Stream parameter to send each string individually, instead of concatenating them into a single s
tring. Another pipeline operator sends the strings to Select-String, which selects the strings that include "Get-Co
mmand" anywhere in the string.

If you omit the Stream parameter, the command displays all of the aliases, because Select-String finds "Get-Command
" in the single string that Out-String returns, and the formatter displays the string as a table.

Online version: http://go.microsoft.com/fwlink/?LinkID=113368