PowerShell Remoting Project Home

Sunday, August 06, 2006

Do You Know There is a $Host Variable

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).

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.

3. Two methods about nested prompt.

I already discussed how to use those methods previously.

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:
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

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

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

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

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:
public enum ReadKeyOptions
      AllowCtrlC = 1,
      IncludeKeyDown = 4,
      IncludeKeyUp = 8,
      NoEcho = 2
For example
> $host.ui.RawUI.ReadKey(12)
     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


Ah, another great post there.

I kind of wished that you could direct users to check out "about_automatic_variables" and look for "$host".

But there is a typo on the documenation. Instead of "$host", there is an entry for "$PsHost",
Contains information about the current host

but it seems to mean "$host" since there is no entry for "$host" and the description on "about_*" doc fits the description of $host according to your blog entry.

Thank you for the great reference again.
Well, come to think of it, "about_" doc doesn't seem to contain a useful info on $host...

By the way, I have just posted about this doc bug on Microsoft Connect site
FeedBack ID: 177597

Oes Tsetnoc one of the ways in which we can learn seo besides Mengembalikan Jati Diri Bangsa. By participating in the Oes Tsetnoc or Mengembalikan Jati Diri Bangsa we can improve our seo skills. To find more information about Oest Tsetnoc please visit my Oes Tsetnoc pages. And to find more information about Mengembalikan Jati Diri Bangsa please visit my Mengembalikan Jati Diri Bangsa pages. Thank you So much.
Oes Tsetnoc | Semangat Mengembalikan Jati Diri Bangsa

Post a Comment

Links to this post:

Create a Link

<< Home