powershellscripts.com

Tutorials  PowerShell Cmdlet Help for Out-String



NAME
Out-String

SYNOPSIS
Sends objects to the host as a series of strings.

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


DESCRIPTION
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.


PARAMETERS
-InputObject
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

-Width
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".

INPUTS
System.Management.Automation.PSObject
You can pipe objects to Out-String.


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


NOTES


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


Description
-----------
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


Description
-----------
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"


Description
-----------
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.






RELATED LINKS
Online version: http://go.microsoft.com/fwlink/?LinkID=113368
Out-File
Out-Null
Out-Host
Out-Printer
Out-Default