Tag Archives: InputObject

Out-Default

February 26, 2014 Adam

SYNOPSIS
Sends the output to the default formatter and to the default output cmdlet.

SYNTAX
Out-Default [-InputObject <psobject>] [<CommonParameters>]

DESCRIPTION
The Out-Default cmdlet sends output to the default formatter and the default output cmdlet. This cmdlet has no effect on the formatting or output of Windows PowerShell commands. It is a placeholder that lets you write your own Out-Default Function or cmdlet.

PARAMETERS
-InputObject <psobject>

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

    <CommonParameters>
        This cmdlet supports the common parameters: Verbose, Debug,
        ErrorAction, ErrorVariable, WarningAction, WarningVariable,
        OutBuffer and OutVariable. For more information, type,
        “Get-Help about_CommonParameters“.

INPUTS

OUTPUTS

NOTES

RELATED LINKS
Online version: http://go.microsoft.com/fwlink/?LinkID=113362

cmdlet, File, Out

Out-File

February 26, 2014 Adam

NAME
Out-File

SYNOPSIS
Sends output to a file.

SYNTAX
Out-File [-FilePath] <string> [[-Encoding] <string>] [-Append] [-Force] [-InputObject <psobject>] [-NoClobber] [-Width <int>] [-Confirm] [-WhatIf] [<CommonParameters>]

DESCRIPTION
The Out-File cmdlet sends output to a file. You can use this cmdlet instead of the redirection operator (>) when you need to use its parameters.

PARAMETERS
-Append [<SwitchParameter>]
Adds the output to the end of an existing file, instead of replacing the file contents.

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

-Encoding <string>
Specifies the type of character encoding used in the file. Valid values are “Unicode”, “UTF7”, “UTF8”, “UTF32”, “ASCII”, “BigEndianUnicode”, “Default”, and “OEM”. “Unicode” is the default.

“Default” uses the encoding of the system’s current ANSI code page.

“OEM” uses the current original equipment manufacturer code page identifier for the operating system.

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

-FilePath <string>
Specifies the path to the output file.

        Required?                    true
        Position?                    1
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

-Force [<SwitchParameter>]
Allows the cmdlet to overwrite an existing read-only file. Even using the Force parameter, the cmdlet cannot override security restrictions.

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

-InputObject <psobject>
Specifies the objects to be written to the file. 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

-NoClobber [<SwitchParameter>]
Will not overwrite (replace the contents) of an existing file. By default, if a file exists in the specified path, Out-File overwrites the file without warning. If both Append and NoClobber are used, the output is appended to the existing file.

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

-Width <int>
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 Windows PowerShell console is 80 (characters).

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

-Confirm [<SwitchParameter>]
Prompts you for confirmation before executing the command.

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

-WhatIf [<SwitchParameter>]
Describes what would happen if you executed the command without actually executing the command.

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

INPUTS
System.Management.Automation.PSObject
You can pipe any object to Out-File.

OUTPUTS
None
Out-File does not generate any output.

NOTES

The Out cmdlets do not format objects; they just render them and send them 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 a cmdlet that contains the Out verb (an Out cmdlet), use a pipeline operator (|) to send the output of a Windows PowerShell command to the cmdlet. You can also store data in a Variable and use the InputObject parameter to pass the data to the cmdlet. For help, see the examples.

Out-File sends data, but it does not emit any output objects. If you pipe the output of Out-File to Get-Member, Get-Member reports that no objects have been specified.

————————– EXAMPLE 1 ————————–

C:\PS>Get-Process | Out-File -FilePath C:\Test1\process.txt

    Description
    ———–
    This command sends a list of processes on the computer to the Process.txt file. If the file does not exist, Out-File creates it. Because the name of the FilePath parameter is optional, you can omit it and submit the equivalent command “Get-Process | outfile C:\Test1\process.txt”.

————————– EXAMPLE 2 ————————–

C:\PS>Get-Process | Out-File C:\Test1\process.txt -NoClobber

    Out-File : File C:\Test1\process.txt already exists and NoClobber was specified.
    At line:1 char:23
    + Get-Process | Out-File <<<< process.txt -NoClobber

    Description
    ———–
    This command also sends a list of processes to the Process.txt file, but it uses the NoClobber parameter, which prevents an existing file from being overwritten. The output shows the error message that appears when NoClobber is used with an existing file.

————————– EXAMPLE 3 ————————–

C:\PS>$a = Get-Process

C:\PS> Out-File -FilePath C:\Test1\process.txt -InputObject $a -Encoding ASCII -Width 50

    Description
    ———–
    These commands send a list of processes on the computer to the Process.txt file. The text is encoded in ASCII format so that it can be read by search programs like Findstr and Grep. By default, Out-File uses Unicode format.

The first command gets the list of processes and stores them in the $a Variable. The second command uses the Out-File cmdlet to send the list to the Process.txt file.

The command uses the InputObject parameter to specify that the input is in the $a Variable. It uses the Encoding parameter to convert the output to ASCII format. It uses the Width parameter to limit each line in the file to 50 characters. Because the lines of output are truncated at 50 characters, the rightmost column in the process table is omitted.

————————– EXAMPLE 4 ————————–

C:\PS>Set-Location hklm:\software

c:\PS>Get-Acl mycompany\mykey | Out-File -FilePath c:\ps\acl.txt

c:\PS>Get-Acl mycompany\mykey | Out-File -FilePath FileSystem::acl.txt

    Description
    ———–
    These commands show how to use the Out-File cmdlet when you are not in a FileSystem drive.

The first command sets the current location to the HKLM:\Software Registry key.

The second and third commands have the same effect. They use the Get-Acl cmdlet to get the security descriptor of the MyKey Registry subkey (HKLM\Software\MyCompany\MyKey). A pipeline operator passes the result to the Out-File cmdlet, which sends it to the Acl.txt file.

Because Out-File is not supported by the Windows PowerShell Registry provider, you must specify either the file system drive name, such as “c:”, or the name of the provider followed by two colons, “FileSystem::”, in the value of the FilePath parameter. The second and third commands demonstrate these methods.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=113363
    Out-String
    Out-Null
    Out-Host
    Out-Printer
    Out-Default
    Tee-Object

cmdlet, GridView, Out

Out-GridView

February 26, 2014 Adam

NAME
Out-GridView

SYNOPSIS
Sends output to an interactive table in a separate window.

SYNTAX
Out-GridView [-InputObject <psobject>] [-Title <string>] [<CommonParameters>]

DESCRIPTION
The Out-GridView cmdlet sends the output from a command to a grid view window where the output is displayed in an interactive table. This feature requires Microsoft .NET Framework 3.5 with Service Pack 1.

You can use the following features of the table to examine your data:

— Hide, Show, and Reorder Columns: To hide, show, or reorder a column, right-click a column header and then click “Select Columns.”

— Sort. To sort the data, click a column header. Click again to toggle from ascending to descending order.

— Quick Filter. Use the “Filter” box at the top of the window to search the text in the table. You can search for text in a particular column, search for literals, and search for multiple words.

— Criteria Filter. Use the “Add criteria” drop-down menu to create rules to filter the data. This is very useful for very large data sets, such as event logs.

— Copy and paste. To copy rows of data from Out-GridView, press CTRL+C (copy). You can paste the data into any text or spreadsheet program.

For instructions for using these features, type “Get-Help Out-GridView -full” and see “How to Use the Grid View Window Features” in the NOTES section.

PARAMETERS
-InputObject <psobject>
Accepts input for Out-GridView.

When you use the InputObject parameter to send a collection (more than one) of objects to Out-GridView, Out-GridView treats the collection as one collection object, and it displays one row that represents the collection. To display the each object in the collection, use a pipeline operator (|) to send objects to Out-GridView.

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

-Title <string>
Specifies the text that appears in the title bar of the Out-GridView window.

By default, the title bar displays the command that invokes Out-GridView.

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

INPUTS
System.Management.Automation.PSObject
You can send any object to Out-GridView.

OUTPUTS
None
Out-GridView does not return any objects.

NOTES

NOTES FOR Out-GridView
———————-

You can download the Microsoft .NET Framework 3.5 with Service Pack 1 from the Microsoft Download Center.

Because this cmdlet requires a user interface, it does not work on Server Core installations of Windows Server.

You cannot use a remote command to open a grid view window on a remote computer.

The command output that you send cannot be pre-formatted, such as by using the Format-Table or Format-Wide cmdlets. To select properties, use the Select-Object cmdlet.

Deserialized output from remote commands might not be formatted correctly in the grid view window.

KEYBOARD SHORTCUTS FOR Out-GridView
———————————–

By using the following keyboard shortcuts, you can perform many tasks quickly.

        Use this key:     To perform this action:
        ————-     —————————————————————-
        TAB             Moves the cursor from the Filter box to the Add criteria menu to the table and back.
        UP ARROW         Move up one row. Will move to column headers.
        DOWN ARROW        Move down one row.
        LEFT ARROW        In column header row, move left one column.
        RIGHT ARROW     In column header row, move right one column.
        CONTEXT MENU KEY In column header row, displays the “Select Columns” option.
        ENTER or SPACEBAR In column header row, sort column data (toggle A-Z, Z-A).

        HOW TO USE THE GRID VIEW WINDOW FEATURES
        —————————————-
        The following topics explain how to use the features of the window that Out-GridView displays.

        How to Hide, Show, and Reorder Columns
        ————————————–
        To hide or show a column:

1. Right click any column header and click “Select Columns”.

2. In the “Select Columns” dialog box, use the arrow keys to move the columns between the “Selected columns” to the “Available columns” boxes. Only columns in the “Selected Columns” box appear in the grid view window.

To reorder columns:

— Drag and drop the column into the desired location.

– or-

1. Right click any column header and click “Select Columns”.

2. In the “Select Columns” dialog box, use the “Move up” and “Move down” buttons to reorder the columns. Columns at the top of the list appear to the left of columns at the bottom of the list in the grid view window.

        How to Sort Table Data
        ———————-
        — To sort the data, click a column header.
        — To change the sort order, click the column header again. Each time you click the same header, the sort order toggles between ascending to descending order. The current order is indicated by a triangle in the column header.

        How to Select Table Data
        ————————
        — To select a row, click the row or use the up or down arrow to navigate to the row.
        — To select all rows (except for the header row), press CTRL+A.
        — To select consecutive rows, press and hold the SHIFT key while clicking the rows or using the arrow keys.
        — To select nonconsecutive rows, press the CTRL key and click to add a row to the selection.
        You cannot select columns, and you cannot select the entire column header row.

        How to Copy Rows
        ———————-
        — To copy one or more rows from the table, select the rows and then press CTRL+C.
        You can paste the data into any text or spreadsheet program. You cannot copy columns or parts of rows and you cannot copy the column header row.

        How to Search in the Table (Quick Filter)
        ———————————
        Use the “Filter” box to search for data in the table. When you type in the box, only items that include the typed text appear in the table.

— Search for text. To search for text in the table, in the “Filter” box, type the text to find.

— Search for multiple words. To search for multiple words in the table, type the words separated by spaces. Out-GridView displays rows that include all of the words (logical AND).

— Search for literal phrases. To search for phrases that include spaces or special characters, enclose the phrase in quotation marks. Out-GridView displays rows that include an exact match for the phrase.

— Search in columns. To search for text in one or more columns, use the following format:

<column>:<text> [<column>:<text>] …

For example, to find “Net” in the DisplayName column, in the “Filter” box, type:

displayname:net

To find rows with “Net” in the DisplayName and Name columns, in the “Filter” box, type:

displayname:net name:net

— Turn off search. To display the entire table again, click the red X button in the top right corner of the “Filter” box or delete the text from the Filter box.

        Use Criteria to Filter the Table
        ——————————–
        You can use rules or “criteria” to determine which items are displayed in the table. Items appear only when they satisfy all of the criteria that you establish. The available criteria are determined by the properties of the objects displayed in the grid view window and the .NET Framework types of those properties.

Each criterion has the following format:
<column> <operator> <value>

Criteria for different properties are connected by AND. Criteria for the same property are connected by OR. You cannot change the logical connectors.

The criteria only affects the display. It does not delete items from the table.

        How to Add Criteria
        —————————
        1. To display the “Add criteria” menu button, in the upper right corner of the window, click the “Expand” arrow.
        2. Click the “Add Criteria” menu button.
        3. Click to select columns (properties). You can select one or many properties.
        4. When you are finished selecting properties, click the Add button.
        5. To cancel the additions, click Cancel.
        6. To add more criteria, click the Add Criteria button again.

        How to Edit a Criterion
        ——————–
        — To change an operator, click the blue operator value, and then click to select a different
         operator from the drop-down list.
        — To enter or change a value, type a value in the value box. If you enter a value that is not valid, a circular X icon appears. To remove it, change the value.
        — To create an OR statement, add a criteria with the same property.

        How to Delete Criteria
        ————————-
        — To delete selected criteria, click the red X beside each criterion.
        — To delete all criteria, click the “Clear All” button.

————————– EXAMPLE 1 ————————–

C:\PS>Get-Process | Out-GridView

    Description
    ———–
    This command gets the processes running on the local computer and sends them to a grid view window.

————————– EXAMPLE 2 ————————–

C:\PS>$p = Get-Process

C:\PS> $p | Out-GridView

    Description
    ———–
    This command also gets the processes running on the local computer and sends them to a grid view window.

The first command uses the Get-Process command to get the processes on the computer and then saves the process objects in the $p Variable.

The second command uses a pipeline operator to send the $p Variable to Out-GridView.

————————– EXAMPLE 3 ————————–

C:\PS>Get-Process | Select-Object -property name, workingset, peakworkingset | Sort-Object -property workingset -desc | Out-GridView

    Description
    ———–
    This command displays a formatted table in a grid view window.

It uses the Get-Process cmdlet to get the processes on the computer.

Then, it uses a pipeline operator (|) to send the process objects to the Select-Object cmdlet. The command uses the Property parameter of Select-Object to select the Name, WorkingSet, and PeakWorkingSet properties to be displayed in the table.

Another pipeline operator sends the filtered objects to the Sort-Object cmdlet, which sorts them in descending order by the value of the WorkingSet property.

The final part of the command uses a pipeline operator (|) to send the formatted table to Out-GridView.

You can now use the features of the grid view to search, sort, and filter the data.

————————– EXAMPLE 4 ————————–

C:\PS>($a = Get-ChildItem -path $pshome -recurse) | Out-GridView

    Description
    ———–
    This command saves its output in a Variable and sends it to Out-GridView.

The command uses the Get-ChildItem cmdlet to get the files in the Windows PowerShell installation directory and its subdirectories. The path to the installation directory is saved in the $pshome automatic Variable.

The command uses the assignment operator (=) to save the output in the $a Variable and the pipeline operator (|) to send the output to Out-GridView.
The parentheses in the command establish the order of operations. As a result, the output from the Get-ChildItem command is saved in the $a Variable before it is sent to Out-GridView.

————————– EXAMPLE 5 ————————–

C:\PS>Get-Process -computername Server01| ogv -Title “Processes – Server01”

    Description
    ———–
    This command displays the processes that are running on the Server01 computer in a grid view window.

The command uses “ogv,” which is the built-in Alias for the Out-GridView cmdlet, it uses the Title parameter to specify the window title.

————————– EXAMPLE 6 ————————–

C:\PS>Invoke-Command -ComputerName S1, S2, S3 -scriptblock {Get-Culture} | Out-GridView

    Description
    ———–
    This example shows the correct format for sending data collected from remote computers to the Out-GridView cmdlet.

The command uses the Invoke-Command cmdlet to run a Get-Culture command on three remote computers. It uses a pipeline operator to send the data that is returned to the Out-GridView cmdlet.

Notice that the script block that contains the commands that are run remotely does not include the Out-GridView command. If it did, the command would fail when it tried to open a grid view window on each of the remote computers.

RELATED LINKS
Online version: http://go.microsoft.com/fwlink/?LinkID=113364

cmdlet, Host, Out

Out-Host

February 26, 2014 Adam

NAME
Out-Host

SYNOPSIS
Sends output to the command line.

SYNTAX
Out-Host [-InputObject <psobject>] [-Paging] [<CommonParameters>]

DESCRIPTION
The Out-Host cmdlet sends output to the Windows PowerShell host for display. The host displays the output at the command line. Because Out-Host is the default, you do not need to specify it unless you want to use its parameters to change the display.

PARAMETERS
-InputObject <psobject>
Specifies the objects that are written to the console. 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

-Paging [<SwitchParameter>]
Displays one page of output at a time, and waits for user input before displaying the remaining pages, much like the traditional “more” command. By default, all of the output is displayed on a single page. The page size is determined by the characteristics of the host.

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

INPUTS
System.Management.Automation.PSObject
You can pipe any object to Out-Host.

OUTPUTS
None
Out-Host does not generate any output. However, the host might display the objects that Out-Host sends to it.

NOTES

You can also refer to Out-Host by its built-in Alias, “oh”. For more information, see about_aliases.

The cmdlets that contain the Out verb (the Out cmdlets) do not format objects; they just render them and send them 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 operator (|) to send the output of a Windows PowerShell command to the cmdlet. You can also store data in a Variable and use the InputObject parameter to pass the data to the cmdlet. For help, see the examples.

Out-Host sends data, but it does not emit any output objects. If you pipe the output of Out-Host to Get-Member, Get-Member reports that no objects have been specified.

————————– EXAMPLE 1 ————————–

C:\PS>Get-Process | Out-Host -Paging

    Description
    ———–
    This command displays the processes on the system one page at a time. It uses the Get-Process command to get the processes on the system. The pipeline operator (|) sends the results to Out-Host, which displays them at the console. The Paging parameter displays one page of data at a time.

The same command format is used for the Help Function that is built into Windows PowerShell. That Function gets data from Get-Help and then uses the Paging parameter of Out-Host to display the data one page at a time by using this command format: Get-Help $args[0] | Out-Host -Paging).

————————– EXAMPLE 2 ————————–

C:\PS>$a = Get-History

C:\PS>Out-Host -InputObject $a

    Description
    ———–
    These commands display the session history at the command line. The first command uses the Get-History cmdlet to get the session history, and then it stores the history in the $a Variable. The second command uses Out-Host to display the content of the $a Variable, and it uses the InputObject parameter to specify the Variable to Out-Host.

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

cmdlet, Null, Out

Out-Null

February 26, 2014 Adam

NAME
Out-Null

SYNOPSIS
Deletes output instead of sending it to the console.

SYNTAX
Out-Null [-InputObject <psobject>] [<CommonParameters>]

DESCRIPTION
The Out-Null cmdlet sends output to NULL, in effect, deleting it.

PARAMETERS
-InputObject <psobject>
Specifies the object that was sent to null (deleted). 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

INPUTS
System.Management.Automation.PSObject
You can pipe any object to Out-Null.

OUTPUTS
None
Out-Null does not generate any output.

NOTES

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

Out-Null does not return any output objects. If you pipe the output of Out-Null to Get-Member, Get-Member reports that no objects have been specified.

————————– EXAMPLE 1 ————————–

C:\PS>Get-ChildItem | Out-Null

    Description
    ———–
    This command gets the items in the local directory, but then it discards them instead of passing them through the pipeline or displaying them at the command line. This is useful for discarding output that you do not need.

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

cmdlet, Out, Printer

Out-Printer

February 26, 2014 Adam

NAME
Out-Printer

SYNOPSIS
Sends output to a printer.

SYNTAX
Out-Printer [[-Name] <string>] [-InputObject <psobject>] [<CommonParameters>]

DESCRIPTION
The Out-Printer cmdlet sends output to the default printer or to an alternate printer, if one is specified.

PARAMETERS
-InputObject <psobject>
Specifies the objects to be sent to the printer. 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

-Name <string>
Specifies the alternate printer. The parameter name (“Name”) is optional.

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

INPUTS
System.Management.Automation.PSObject
You can pipe any object to Out-Printer.

OUTPUTS
None
Out-Printer does not return any objects.

NOTES

You can also refer to Out-Printer by its built-in Alias, “lp”. For more information, see about_aliases.

Out-Printer sends data, but it does not emit any output objects. If you pipe the output of Out-Printer to Get-Member, Get-Member reports that no objects have been specified.

————————– EXAMPLE 1 ————————–

C:\PS>Get-Content $pshome\about_signing.help.txt | Out-Printer

    Description
    ———–
    This command prints the content of the about_Signing Help topic to the default printer. This example shows you how to print a file, even though Out-Printer does not have a Path parameter.

The command uses the Get-Content cmdlet to get the contents of the Help topic. The path includes $pshome, a built-in Variable that stores the installation directory for Windows PowerShell. A pipeline operator (|) passes the results to Out-Printer, which sends it to the default printer.

————————– EXAMPLE 2 ————————–

C:\PS>”Hello, World” | Out-Printer -Name “\\Server01\Prt-6B Color”

    Description
    ———–
    This command prints “Hello, World” to the “Prt-6B Color” printer on Server01. This command uses the Name parameter to specify the alternate printer. Because the parameter name is optional, you can omit it.

————————– EXAMPLE 3 ————————–

C:\PS>$h = Get-Help -full Get-WmiObject

C:\PS> Out-Printer -InputObject $h

    Description
    ———–
    These commands print the full version of the Help topic for Get-WmiObject. The first command uses the Get-Help cmdlet to get the full version of the Help topic for Get-WmiObject and stores it in the $h Variable. The second command sends the content to the default printer. It uses the InputObject parameter to pass the value of the $h Variable to Out-Printer.

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

cmdlet, Out, String

Out-String

February 26, 2014 Adam

NAME
Out-String

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

SYNTAX
Out-String [-InputObject <psobject>] [-Stream] [-Width <int>] [<CommonParameters>]

DESCRIPTION
The Out-String cmdlet converts the objects that Windows PowerShell manages into an array of strings. By default, Out-String accumulates the strings and returns them as a single string, but you can use the stream parameter to direct 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 <psobject>
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 [<SwitchParameter>]
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

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

————————– 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 uses the Get-Culture cmdlet to get the regional settings. The pipeline operator (|) sends the result to the Select-Object cmdlet, which selects all properties (*) of the culture object that Get-Culture retrieved. The command then stores 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 property). 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 AliasInfo objects (one for each Alias in the current session). This example demonstrates the difference between working 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 strings. It uses the Stream parameter to send each string individually, instead of concatenating them into a single string. Another pipeline operator sends the strings to Select-String, which selects the strings that include “Get-Command” 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

cmdlet, Command, Measure

Measure-Command

February 26, 2014 Adam

NAME
Measure-Command

SYNOPSIS
Measures the time it takes to run script blocks and cmdlets.

SYNTAX
Measure-Command [-Expression] <scriptblock> [-InputObject <psobject>] [<CommonParameters>]

DESCRIPTION
The Measure-Command cmdlet runs a script block or cmdlet internally, times the execution of the operation, and returns the execution time.

PARAMETERS
-Expression <scriptblock>
Specifies the expression that is being timed. Enclose the expression in curly braces ({}). The parameter name (“Expression”) is optional.

        Required?                    true
        Position?                    1
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

-InputObject <psobject>
Specifies objects representing the expressions to be measured. 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

INPUTS
System.Management.Automation.PSObject
You can pipe an object to Measure-Command.

OUTPUTS
System.TimeSpan
Measure-Command returns a time span object that represents the result.

NOTES

For more information, type “Get-Help Measure-Command -detailed”. For technical information, type “Get-Help Measure-Command -full”.

When specifying multiple values for a parameter, use commas to separate the values. For example, “<parameter-name> <value1>, <value2>”.

————————– EXAMPLE 1 ————————–

C:\PS>Measure-Command { Get-Eventlog “windows powershell” }

    Description
    ———–
    This command measures the time it takes to run a “Get-Eventlog” command that gets the events in the Windows PowerShell event log.

————————– EXAMPLE 2 ————————–

C:\PS>Measure-Command {Get-ChildItem c:\windows -include *.txt -recurse}

    Days             : 0
    Hours             : 0
    Minutes         : 0
    Seconds         : 8
    Milliseconds     : 618
    Ticks             : 86182763
    TotalDays         : 9.9748568287037E-05
    TotalHours        : 0.00239396563888889
    TotalMinutes     : 0.143637938333333
    TotalSeconds     : 8.6182763
    TotalMilliseconds : 8618.2763

C:\PS>Measure-Command {Get-ChildItem c:\windows -filter “*.txt” -recurse}

    Days             : 0
    Hours             : 0
    Minutes         : 0
    Seconds         : 1
    Milliseconds     : 140
    Ticks             : 11409189
    TotalDays         : 1.32050798611111E-05
    TotalHours        : 0.000316921916666667
    TotalMinutes     : 0.019015315
    TotalSeconds     : 1.1409189
    TotalMilliseconds : 1140.9189

    Description
    ———–
    These commands show the value of using a provider-specific filter in Windows PowerShell commands. The first command measures the time it takes to process a recursive Get-ChildItem command that uses the Include parameter. The second command measures the time it takes to process a recursive Get-ChildItem command that uses the provider-specific Filter parameter.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=113348
    Trace-Command
    Invoke-Command

cmdlet, Measure, Object

Measure-Object

February 26, 2014 Adam

NAME
Measure-Object

SYNOPSIS
Calculates the numeric properties of objects, and the characters, words, and lines in string objects, such as files of text.

SYNTAX
Measure-Object [-Average] [-Maximum] [-Minimum] [-Sum] [[-Property] <string[]>] [-InputObject <psobject>] [<CommonParameters>]

Measure-Object [-Character] [-IgnoreWhiteSpace] [-Line] [-Word] [[-Property] <string[]>] [-InputObject <psobject>] [<CommonParameters>]

DESCRIPTION
The Measure-Object cmdlet calculates the property values of certain types of object. Measure-Object performs three types of measurements, depending on the parameters in the command.
The Measure-Object cmdlet performs calculations on the property values of objects. It can count objects and calculate the minimum, maximum, sum, and average of the numeric values. For text objects, it can count and calculate the number of lines, words, and characters.

PARAMETERS
-Average [<SwitchParameter>]
Displays the average value of the specified properties.

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

-Character [<SwitchParameter>]
Counts the number of characters in the input object.

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

-IgnoreWhiteSpace [<SwitchParameter>]
Ignores white space in word counts and character counts. By default, white space is not ignored.

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

-InputObject <psobject>
Specifies the objects to be measured. 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

-Line [<SwitchParameter>]
Counts the number of lines in the input object.

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

-Maximum [<SwitchParameter>]
Displays the maximum value of the specified properties.

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

-Minimum [<SwitchParameter>]
Displays the minimum value of the specified properties.

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

-Property <string[]>
Specifies one or more numeric properties to measure. The default is the Count (Length) property of the object.

        Required?                    false
        Position?                    1
        Default value                Count
        Accept pipeline input?     false
        Accept wildcard characters? false

-Sum [<SwitchParameter>]
Displays the sum of the values of the specified properties.

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

-Word [<SwitchParameter>]
Counts the number of words in the input object.

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

INPUTS
System.Management.Automation.PSObject
You can pipe objects to Measure-Object.

OUTPUTS
GenericMeasureInfo or TextMeasureInfoObject

NOTES

————————– EXAMPLE 1 ————————–

C:\PS>Get-ChildItem | Measure-Object

    Description
    ———–
    This command counts the files and folders in the current directory.

————————– EXAMPLE 2 ————————–

C:\PS>Get-ChildItem | Measure-Object -Property length -Minimum -Maximum -Average

    Description
    ———–
    This command displays the minimum, maximum, and sum of the sizes of all files in the current directory, and the average size of a file in the directory.

————————– EXAMPLE 3 ————————–

C:\PS>Get-Content C:\test.txt | Measure-Object -character -line -word

    Description
    ———–
    This command displays the number of characters, words, and lines in the Text.txt file.

————————– EXAMPLE 4 ————————–

C:\PS>Get-Process | Measure-Object -Property workingset -Minimum -Maximum -Average

    Description
    ———–
    This command displays the minimum, maximum, and average sizes of the working sets of the processes on the computer.

————————– EXAMPLE 5 ————————–

C:\PS>Import-Csv d:\test\serviceyrs.csv | Measure-Object -Property years -Minimum -Maximum -Average

    Description
    ———–
    This command calculates the average years of service of the employees of a company.

The ServiceYrs.csv file is a CSV file that contains the employee number and years of service of each employee. The first row in the table is a header row of “EmpNo, Years”.

When you use Import-Csv to import the file, the result is a PSCustomObject with note properties of EmpNo and Years. You can use Measure-Object to calculate the values of these properties, just like any other property of an object.

————————– EXAMPLE 6 ————————–

C:\PS>Get-ChildItem | Measure-Object -Property psiscontainer -max -Sum -min -Average

    Count    : 126
    Average : 0.0634920634920635
    Sum     : 8
    Maximum : 1
    Minimum : 0
    Property : PSIsContainer

    Description
    ———–
    This example demonstrates the Measure-Object can measure Boolean values. In this case, it uses the PSIsContainer Boolean property to measure the incidence of folders (vs. files) in the current directory.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=113349
    Compare-Object
    ForEach-Object
    Group-Object
    New-Object
    Select-Object
    Sort-Object
    Tee-Object
    Where-Object

cmdlet, Group, Object

Group-Object

February 26, 2014 Adam

NAME
Group-Object

SYNOPSIS
Groups objects that contain the same value for specified properties.

SYNTAX
Group-Object [-AsHashTable] [-AsString] [[-Property] <Object[]>] [-CaseSensitive] [-Culture <string>] [-InputObject <psobject>] [-NoElement] [<CommonParameters>]

DESCRIPTION
The Group-Object cmdlet displays objects in groups based on the value of a specified property. Group-Object returns a table with one row for each property value and a column that displays the number of items with that value.

If you specify more than one property, Group-Object first groups them by the values of the first property, and then, within each property group, it groups by the value of the next property.

PARAMETERS
-AsHashTable [<SwitchParameter>]
Returns the group as a hash table. The keys of the hash table are the property values by which the objects are grouped. The values of the hash table are the objects that have that property value.

By itself, the AsHashTable parameter returns each hash table in which each key is an instance of the grouped object. When used with the AsString parameter, the keys in the hash table are strings.

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

-AsString [<SwitchParameter>]
Converts the hash table keys to strings. By default, the hash table keys are instances of the grouped object. This parameter is valid only when used with the AsHashTable parameter.

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

-CaseSensitive [<SwitchParameter>]
Makes the grouping case-sensitive. Without this parameter, the property values of objects in a group might have different cases.

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

-Culture <string>
Specifies the culture to use when comparing strings.

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

-InputObject <psobject>
Specifies the objects to group. Enter a Variable that contains the objects, or type a command or expression that gets the objects.

When you use the InputObject parameter to submit a collection of objects to Group-Object, Group-Object receives one object that represents the collection. As a result, it creates a single group with that object as its member.

To group the objects in a collection, pipe the objects to Group-Object.

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

-NoElement [<SwitchParameter>]
Omits the members of a group from the results.

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

-Property <Object[]>
Specifies the properties for grouping. The objects are arranged into groups based on the value of the specified property.

The value of the Property parameter can be a new calculated property. To create a calculated, property, create a hash table with an Expression key that specifies a string or script block value.

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

INPUTS
System.Management.Automation.PSObject
You can pipe any object to Group-Object

OUTPUTS
Microsoft.PowerShell.Commands.GroupInfo or System.Collections.Hashtable
When you use the AsHashTable parameter, Group-Object returns a hash table. Otherwise, it returns a GroupInfo object.

NOTES

You can also use the GroupBy parameter of the formatting cmdlets (such as Format-Table [m2] and Format-List [m2]) to group objects. Unlike Group-Object, which creates a single table with a row for each property value, the GroupBy parameters create a table for each property value with a row for each item that has the property value.

Group-Object does not require that the objects being grouped be of the same Microsoft .NET Framework type. When grouping objects of different .NET Framework types, Group-Object uses the following rules:

— Same Property Names and Types: If the objects have a property with the specified name, and the property values have the same .NET Framework type, the property values are grouped by using the same rules that would be used for objects of the same type.

— Same Property Names, Different Types: If the objects have a property with the specified name, but the property values have a different .NET Framework type in different objects, Group-Object uses the .NET Framework type of the first occurrence of the property as the .NET Framework type for that property group. When an object has a property with a different type, the property value is converted to the type for that group. If the type conversion fails, the object is not included in the group.

— Missing Properties: Objects that do not have a specified property are considered ungroupable. Ungroupable objects appear in the final GroupInfo object output in a group named AutomationNull.Value.

————————– EXAMPLE 1 ————————–

C:\PS>Get-ChildItem *.doc | Group-Object -Property length

    Description
    ———–
    This command gets the files in the current location that have a .doc extension and groups them by size.

————————– EXAMPLE 2 ————————–

C:\PS>Get-ChildItem | Sort-Object -Property extension | Group-Object -Property extension

    Description
    ———–
    This command gets the files in the current location, sorts them by file name extension, and then groups them by file name extension. Note that the files are sorted before they are grouped.

————————– EXAMPLE 3 ————————–

C:\PS>1..35 | Group-Object -Property {$_ % 2},{$_ % 3}

    Description
    ———–
    This example shows how to use script blocks as the value of the Property parameter.

This command displays the integers from 1 to 35, grouped by the remainder left when they are divided by 2 or 3.

————————– EXAMPLE 4 ————————–

C:\PS>$events = Get-Eventlog -logname system -newest 1000

C:\PS> $events | Group-Object -Property eventID

    Count Name                     Group
    —– —-                     —–
     44 Information             {System.Diagnostics.EventLogEntry,
        5 Error                     {System.Diagnostics.EventLogEntry,
        1 Warning                 {System.Diagnostics.EventLogEntry}

    Description
    ———–
    These commands display the 1,000 most recent entries in the System event log, grouped by Event ID.

The first command uses the Get-EventLog cmdlet to retrieve the events and the assignment operator (=) to save them in the $events Variable.

The second command uses a pipeline operator (|) to send the events in the $events Variable to the Group-Object cmdlet. The command uses the Property parameter to specify that the events should be grouped according to the value of their EventID property.

In the output, the Count column represents the number of entries in each group, the Name column represents the EventID values that define a group, and the Group column represents the objects in each group.

————————– EXAMPLE 5 ————————–

C:\PS>Get-Process | Group-Object -Property priorityclass

    Count Name                Group
    —– —-                —–
     55 Normal             {System.Diagnostics.Process (AdtAgent), System.Diagnostics.Process (alg), System.Dia…
        1                     {System.Diagnostics.Process (Idle)}
        3 High                {System.Diagnostics.Process (Newproc), System.Diagnostics.Process (winlogon), System.D…
        2 BelowNormal         {System.Diagnostics.Process (winperf),

    C:\PS>Get-Process | Group-Object -Property company -NoElement
    Count Name
    —– —-
     55 Normal
        1
        3 High
        2 BelowNormal

    Description
    ———–
    This example demonstrates the effect of the NoElement parameter. These commands group the processes on the computer by priority class.

The first command uses the Get-Process cmdlet to get the processes on the computer. It uses a pipeline operator (|) to send the results to Group-Object, which groups the objects by the value of the PriorityClass property of the process.

The second command is identical to the first, except that it uses the NoElement parameter to eliminate the members of the group from the output. The result is a table with only the count and property value name.

The results are shown in the following sample output.

————————– EXAMPLE 6 ————————–

C:\PS>Get-Eventlog -logname system -newest 1000 | Group-Object -Property {$_.TimeWritten – $_.TimeGenerated}

    Description
    ———–
    This command demonstrates how to provide the value of the Property parameter as a script block.

This command displays the most recent 1,000 entries from the system event log, grouped according to the time between when they were generated and when they were written to the log.

The command uses the Get-EventLog cmdlet to get the event log entries. It uses a pipeline operator (|) to send the entries to the Group-Object cmdlet. The value of the Property parameter is specified as a script block (an expression in braces). The result of evaluating the script block is the time between when the log entry was generated and when it was written to the log. That value is used to group the 1,000 most recent events.

————————– EXAMPLE 7 ————————–

C:\PS>Get-ChildItem | Group-Object extension -NoElement

    Count Name
    —– —-
     21
     82 .txt
        9 .cmd
        5 .log
     12 .xml
        5 .htm
     36 .ps1
        1 .psc1
        3 .exe
        6 .csv
        1 .psd1
        2 .bat

    Description
    ———–
    This command groups the items in the current directory by file name extension. It uses the NoElement parameter to omit the members of the group.

The results are shown in the following sample output.

————————– EXAMPLE 8 ————————–

C:\PS>”a”, “b”, “c”, “c”, “d” | Get-Unique

    a
    b
    c
    d

    C:\PS> “a”, “b”, “c”, “c”, “d” | Group-Object -NoElement | where {$_.Count -gt 1}
    Count Name
    —– —-
        2 c

    C:\PS> Get-Process | Group-Object -Property Name -NoElement | where {$_.count -gt 1}
    Count Name
    —– —-
        2 csrss
        5 svchost
        2 winlogon
        2 wmiprvse

    Description
    ———–
    This example shows how to find the unique and non-unique (repeated) property values in a collection.

The first command gets the unique elements of an array by piping the array to the Get-Unique cmdlet.

The second command gets the non-unique elements of an array. It pipes the array to the Group-Object cmdlet, which groups the objects by value. The resulting groups are piped to the Where-Object cmdlet, which selects objects with groups with more than one member.

The third command shows a practical use for this technique. It uses the same method to find processes on the computer that have the same process name.

The results are shown in the following sample output.

————————– EXAMPLE 9 ————————–

C:\PS>$a = Get-Command get-*, set-* -type cmdlet | Group-Object -Property verb -AsHashTable -AsString

C:\PS> $a

    Name    Value
    —-    —–
    Get     {Get-PSCallStack, Get-PSBreakpoint, Get-PSDrive, Get-PSSession…}
    Set     {Set-Service, Set-StrictMode, Set-PSDebug, Set-PSSessionConfiguration…}

C:\PS> $a.get

    CommandType     Name                 Definition
    ———–     —-                 ———-
    Cmdlet         Get-PSCallStack     Get-PSCallStack [-Verbose] [-Debug] [-ErrorAction <ActionPrefer…
    Cmdlet         Get-PSBreakpoint     Get-PSBreakpoint [[-Id] <Int32[]>] [-Verbose] [-Debug] [-ErrorA…
    Cmdlet         Get-PSDrive         Get-PSDrive [[-Name] <String[]>] [-Scope <String>] [-PSProvider…
    …

    Description
    ———–
    This example uses the AsHashTable and AsString parameters to return the groups in a hash table, that is, as a collection of key-value pairs.

In the resulting hash table, each property value is a key, and the group elements are the values. Because each key is a property of the hash table object, you can use dot notation to display the values.

The first command gets the Get and Set cmdlets in the session, groups them by verb, returns the groups as a hash table, and saves the hash table in the $a Variable.

The second command displays the hash table in $a. There are two key-value pairs, one for the Get cmdlets and one for the Set cmdlets.

The third command uses dot notation to display the values of the Get key in $a. The values are CmdletInfo object. The AsString parameter does not convert the objects in the groups to strings.

RELATED LINKS
Online version: http://go.microsoft.com/fwlink/?LinkID=113338