Capture console screen

Seeing nicely formatted console examples in a previous post has inspired me to write a script that captures the console screen buffer directly from the Windows PowerShell console host. With this script you can make console "screen shots" to demonstrate some of your favorite Windows PowerShell concepts, and then post them to your blog, or put them on your Web site.

How is it done? The console host has a powerful API that is somewhat neglected by most script writers. This API allows you to capture console screen rectangles or output a colorized text in arbitrary areas of the screen. The console API functions are available in Windows PowerShell as properties and methods of the $Host.UI and $Host.UI.RawUI objects.

The script makes a good use of one of this methods – $Host.UI.RawUI.GetBufferContents. This method extracts a rectangular region of the screen buffer. We will use it to capture the console screen buffer contents from the top left corner to the current cursor position.

Note that $Host.UI and $Host.UI.RawUI are fully supported only on Windows PowerShell console, the one that is started by running powershell.exe. Windows PowerShell ISE does not implement all of these interfaces and therefore cannot be used to run this script.

To use the script, just open the Windows PowerShell console, run commands that you want to demonstrate, and then run this script to capture the console screen buffer.

Windows PowerShell V2                                                                                                  
Copyright (C) 2008 Microsoft Corporation. All rights reserved.                                                         
                                                                                                                       
PS C:\Users\Vladimir> cd E:\MyScripts                                                                                  
PS E:\MyScripts> .\RunMyCoolDemo.ps1                                                                                   
                                                                                                                       
Here are colors which you can use in Windows PowerShell console:                                                       
                                                                                                                       
   Black                                                                                                               
   DarkBlue                                                                                                            
   DarkGreen                                                                                                           
   DarkCyan                                                                                                            
   DarkRed                                                                                                             
   DarkMagenta                                                                                                         
   DarkYellow                                                                                                          
   Gray                                                                                                                
   DarkGray                                                                                                            
   Blue                                                                                                                
   Green                                                                                                               
   Cyan                                                                                                                
   Red                                                                                                                 
   Magenta                                                                                                             
   Yellow                                                                                                              
   White                                                                                                               
                                                                                                                       
Note that DarkMagenta and DarkYellow colors are redefined to produce these nice tints of white and blue which are used 
as default Foreground and Background colors.                                                                           
                                                                                                                       
PS E:\MyScripts> $textFileName = "$env:temp\ConsoleBuffer.txt"                                                         
PS E:\MyScripts> .\Get-ConsoleAsText | out-file $textFileName -encoding ascii                                          
PS E:\MyScripts> $null = [System.Diagnostics.Process]::Start("$textFileName")                                          
PS E:\MyScripts>                                                                                                       

#################################################################################################################
# Get-ConsoleAsText.ps1
#
# The script captures console screen buffer up to the current cursor position and returns it in plain text format.
#
# Returns: ASCII-encoded string.
#
# Example:
#
# $textFileName = "$env:temp\ConsoleBuffer.txt"
# .\Get-ConsoleAsText | out-file $textFileName -encoding ascii
# $null = [System.Diagnostics.Process]::Start("$textFileName")
#

# Check the host name and exit if the host is not the Windows PowerShell console host.
if ($host.Name -ne ‘ConsoleHost’)
{
  write-host -ForegroundColor Red "This script runs only in the console host. You cannot run this script in $($host.Name)."
  exit -1
}

# Initialize string builder.
$textBuilder = new-object system.text.stringbuilder

# Grab the console screen buffer contents using the Host console API.
$bufferWidth = $host.ui.rawui.BufferSize.Width
$bufferHeight = $host.ui.rawui.CursorPosition.Y
$rec = new-object System.Management.Automation.Host.Rectangle 0,0,($bufferWidth – 1),$bufferHeight
$buffer = $host.ui.rawui.GetBufferContents($rec)

# Iterate through the lines in the console buffer.
for($i = 0; $i -lt $bufferHeight; $i++)
{
  for($j = 0; $j -lt $bufferWidth; $j++)
  {
    $cell = $buffer[$i,$j]
    $null = $textBuilder.Append($cell.Character)
  }
  $null = $textBuilder.Append("`r`n")
}

return $textBuilder.ToString()