PowerShell For Fun

PowerShell has a build-in $host variable which expose a System. Management. Automation. Internal. Host. InternalHost object. It is an internal object so you can't access it from assembly but monad team made it directly accessible from PowerShell script. $host is interesting and powerful. Just an example how powerful it is: my PowerShell Remoting "steal" the $host.UI for user interface remoting.

$Host is an implementation of System. Management. Automation. Host. PSHost abstract class. PSHost defined some important properties and methods which will be used for all cmdlet. For more detailed information about PSHost, you can consult Monad SDK online.

Let's see what we can do with $host
1. Some read-only properties provide information about current host.
These could be useful when you have to distinguish among multiple hosts (For example, my PowerShell Remoting has a remote host. Remote host have different Name, InstanceId, Version, etc).

• CurrentCulture
• CurrentUICulture
• InstanceId
• Name
• PrivateData
• Version

2. Two methods to support legacy application (like ping.exe).
Usually you do not need to call them directly. Monad engine will call them automatically if you invoke legacy application.

• NotifyBeginApplication()
• NotifyEndApplication()

3. Two methods about nested prompt.
I already discussed how to use those methods previously.

• EnterNestedPrompt()
• ExitNestedPrompt()

4. One method to force PowerShell exit.
This could be useful if some sever error occurs and you want to quit PowerShell.exe from your script. You can also pass error code to environment. For example:

>$host.SetShouldExit(10000)

5. $host.UI
This is an implementation of PSHostUserInterface object which expose some import user interface API.

5.1 public override Dictionary<string, PSObject> Prompt(string caption, string message, Collection<FieldDescription> descriptions)
This API is called when cmdlet required field(s) is null or empty. It is capable of get user input ([string]) and cnvert them to almost any .Net type in current appdomain. But the task of constructing Collection<FieldDescription> from script can be daunting.

5.2 public override int PromptForChoice(string caption, string message, Collection<ChoiceDescription> choices, int defaultChoice)
This is standard PowerShell text-base menu system. Don't re-invent wheels! If you want to provide a menu for user input, look nowhere and this method got you all covered. Mow has a nice example of how to use this methods.

5.3 Some more input API to get user input

• ReadLine: Read a line from standard input, similar to read-host cmdlet
• PromptForCredential: Get PSCredential object from User input, similar to get-credential cmdlet.
• ReadLineAsSecureString: read from standard input and convert to SecureString, similar to Read-host -AsSecureString

5.4 Some output API to direct output to different channel and with color support.

• Write: Write to standard output without /n/r
• WriteLine: Write a line to standard output
• WriteProgress: Wrtie to Progress panel, similar to Write-progress cmdlet
• WriteDebugLine: Write to Debug channel, similar to Write-debug cmdlet
• WriteErrorLine: Write to Standard Error, similar to Write-error cmdlet
• WriteVerboseLine: Write to Verbose channel, similar to Write-verbose cmdlet
• WriteWarningLine: Wrtie to Warning channel, similar to Write-warning cmdlet

5.5 $Host.UI.RawUI
This is an implementation of PSHostRawUserInterface abstract class. This is a new concept in PowerShell. In the prompt post, we use this object to do a lot of tricks.

5.5.1 Some properties to control Console window size, window title, cursor, buffer size, background/foreground color

• BackgroundColor
• BufferSize
• CursorPosition
• CursorSize
• ForegroundColor
• KeyAvailable
• MaxPhysicalWindowSize
• MaxWindowSize
• WindowPosition
• WindowSize
• WindowTitle

5.5.2 Some console buffer API. Lee has a great burn-console script to demonstrate these methods.

• FlushInputBuffer
• GetBufferContents
• LengthInBufferCells
• NewBufferCellArray
• ScrollBufferContents
• SetBufferContents

5.5.3   public override KeyInfo ReadKey(ReadKeyOptions options)
It is a powerful API to read keyboard input. Check out the retuned KeyInfo object, with this method, one can theoretically write a script act like a simple screen editor.
Here is the ReadKeyOption enum:

[Flags]
public enum ReadKeyOptions
{
      AllowCtrlC = 1,
      IncludeKeyDown = 4,
      IncludeKeyUp = 8,
      NoEcho = 2
}

For example

> $host.ui.RawUI.ReadKey(12)
a
     VirtualKeyCode           Character     ControlKeyState             KeyDown
     --------------           ---------     ---------------             -------
                 65                   a              262176                True

Just to remind you, my PowerShell Remoting remote host implemented all Host, UI and RawUI. So feel free to explore those interesting API on you remote host.

Have Fun

Tags: msh    monad   PowerShell