ConsoleGuiTools - Out-ConsoleGridView and Show-ObjectTree
[!IMPORTANT]
The PowerShell team has decided that Microsoft.PowerShell.ConsoleGuiTools is feature complete, so v0.7.7 is the last feature release.
@tig, the author of Terminal.Gui, is maintaining a community fork at tui-cs/PSTui. Users are encouraged to migrate to it going forward. We thank everyone for their contributions.
This repo contains the Out-ConsoleGridView
PowerShell Cmdlet providing console-based GUI experiences based on
Terminal.Gui (gui.cs).
Note: A module named Microsoft.PowerShell.GraphicalTools used to be built and published out of this repo, but per #101 it is deprecated and unmaintained until such time that it can be rewritten on top of .NET MAUI.
Installation
Install-Module Microsoft.PowerShell.ConsoleGuiTools
Features
-
Out-ConsoleGridview - Send objects to a grid view window for interactive filtering and sorting.
-
Show-ObjectTree - Send objects to a tree view window for interactive filtering and sorting.
-
Cross-platform - Works on any platform that supports PowerShell 7.2+.
-
Interactive - Use the mouse and keyboard to interact with the grid or tree view.
-
Filtering - Filter the data using the built-in filter box.
-
Sorting - Sort the data by clicking on the column headers.
-
Multiple Selection - Select multiple items and send them down the pipeline.
-
Customizable - Customize the grid view window with the built-in parameters.
Examples
Example 1: Output processes to a grid view
Get-Process | Out-ConsoleGridView
This command gets the processes running on the local computer and sends them to a grid view window.
Example 2: Use a variable to output processes to a grid view
$P = Get-Process
$P | Out-ConsoleGridView -OutputMode Single
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 cmdlet 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-ConsoleGridView.
By specifying -OutputMode Single the grid view window will be restricted to a single selection, ensuring no more than a single object is returned.
Example 3: Display a formatted table in a grid view
Get-Process | Select-Object -Property Name, WorkingSet, PeakWorkingSet | Sort-Object -Property WorkingSet -Descending | Out-ConsoleGridView
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-ConsoleGridView.
You can now use the features of the grid view to search, sort, and filter the data.
Example 4: Save output to a variable, and then output a grid view
($A = Get-ChildItem -Path $pshome -Recurse) | Out-ConsoleGridView
This command saves its output in a variable and sends it to Out-ConsoleGridView.
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-ConsoleGridView.
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-ConsoleGridView.
Example 5: Output processes for a specified computer to a grid view
Get-Process -ComputerName "Server01" | ocgv -Title "Processes - Server01"
This command displays the processes that are running on the Server01 computer in a grid view window.
The command uses ocgv, which is the built-in alias for the Out-ConsoleGridView cmdlet, it uses the Title parameter to specify the window title.
Example 6: Define a function to kill processes using a graphical chooser
function killp { Get-Process | Out-ConsoleGridView -OutputMode Single -Filter $args[0] | Stop-Process -Id {$_.Id} }
killp note
This example shows defining a function named killp that shows a grid view of all running processes and allows the user to select one to kill it.
The example uses the -Filter paramter to filter for all proceses with a name that includes note (thus highlighting Notepad if it were running. Selecting an item in the grid view and pressing ENTER will kill that process.
Example 7: Use F7 as "Show Command History"
Add gui-cs/F7History to your Powershell profile.
Press F7 to see the history for the current PowerShell instance
Press Shift-F7 to see the history for all PowerShell instances.
Whatever you select within Out-ConsoleGridView will be inserted on your command line.
Whatever was typed on the command line prior to hitting F7 or Shift-F7 will be used as a filter.
Example 8: Output processes to a tree view
PS C:\> Get-Process | Show-ObjectTree
This command gets the processes running on the local computer and sends them to a tree view window.
Use right arrow when a row has a + symbol to expand the tree. Left arrow will collapse the tree.
Development
1. Install PowerShell 7.2+
Install PowerShell 7.2+ with these instructions.
2. Clone the GitHub repository
git clone https://github.com/PowerShell/ConsoleGuiTools.git
3. Install Invoke-Build
Install-Module InvokeBuild -Scope CurrentUser
Now you're ready to build the code. You can do so in one of two ways:
4. Building the code from PowerShell
pushd ./ConsoleGuiTools
Invoke-Build Build -ModuleName Microsoft.PowerShell.ConsoleGuiTools
popd
From there you can import the module that you just built for example (start a fresh pwsh instance first so you can unload the module with an exit; otherwise building again may fail because the .dll will be held open):
pwsh
Import-Module ./module/Microsoft.PowerShell.ConsoleGuiTools
And then run the cmdlet you want to test, for example:
Get-Process | Out-ConsoleGridView
exit
NOTE: If you change the code and rebuild the project, you'll need to launch a
new PowerShell process since the DLL is already loaded and can't be unloaded.
5. Debugging in Visual Studio Code
code ./ConsoleGuiTools
Build by hitting Ctrl-Shift-B in VS Code.
Set a breakpoint and hit F5 to start the debugger.
Click on the VS Code "TERMINAL" tab and type your command that starts Out-ConsoleGridView, e.g.
ls | ocgv
Your breakpoint should be hit.
Contributions Welcome
We would love to incorporate community contributions into this project. If
you would like to contribute code, documentation, tests, or bug reports,
please read the development section above
to learn more.
Microsoft.PowerShell.ConsoleGuiTools Architecture
ConsoleGuiTools consists of 2 .NET Projects:
- ConsoleGuiTools - Cmdlet implementation for Out-ConsoleGridView
- OutGridView.Models - Contains data contracts between the GUI & Cmdlet
Note: Previously, this repo included Microsoft.PowerShell.GraphicalTools which included the Avalonia-based Out-GridView (implemented in .\Microsoft.PowerShell.GraphicalTools and .\OutGridView.Gui). These components have been deprecated (see note above).
Maintainers
- Andy Jordan - @andyleejordan
- Tig Kindel - @tig
Originally authored by Tyler Leonhardt.
License
This project is licensed under the MIT License.
Code of Conduct
Please see our Code of Conduct before participating in this project.
Security Policy
For any security issues, please see our Security Policy.
