Out-GridView
Applies To: Windows PowerShell 2.0
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 |
none |
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 |
<CommonParameters>
This command supports the common parameters: Verbose, Debug, ErrorAction, ErrorVariable, OutBuffer, OutVariable, WarningAction, and WarningVariable. For more information, see about_CommonParameters.
Inputs and Outputs
The input type is the type of the objects that you can pipe to the cmdlet. The return type is the type of the objects that the cmdlet returns.
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.