Read-Host and the ChoiceDescription class – Prompt for user input in PowerShell

• Author
• Recent Posts

Adam Bertram

Adam Bertram is a 20-year IT veteran, Microsoft MVP, blogger, and trainer.

Latest posts by Adam Bertram (see all)

• Create a certificate-signed RDP shortcut via Group Policy - Fri, Aug 9 2019
• Monitor web server uptime with a PowerShell script - Tue, Aug 6 2019
• How to build a PowerShell inventory script for Windows Servers - Fri, Aug 2 2019

A good PowerShell automation script typically requires no interactivity. After all, if a script is interactive, that means a human must be in front of it to press a key. We try to stay away from that by defining all the scenarios ahead of time and feeding parameters into our scripts at runtime with no interaction. However, there are times when we need to gather input where we can't define scenarios ahead of time or we're building scripts for end users.

PowerShell has a few ways to introduce interactivity into our scripts. Today, we're going to discuss two of them: using the Read-Host command and creating our custom selection menu using the .NET System.Management.Automation.Host.ChoiceDescription object.

Prompting for user input with Read-Host ^

The easiest and most common way to add interactivity to your scripts is by using the built-in Read-Host command. This command pauses the script wherever it occurs and expects some input. By default, it will simply stop code execution with no indication of what's going on besides a flashing prompt. So it's important to use the Prompt parameter, which displays some text before it prompts for input.

Prompting for input with Read Host

You can see from the screenshot above that when input occurs, the command then returns that input. I typed Red as input, and it returned Red. This doesn't do much good if we're not capturing that input somehow and making a decision from it. It's best we send that output to a variable. At that point, we can then perform a series of checks against the input provided.

PS C:\> $favColor = Read-Host -Prompt 'What is your favorite color?'
What is your favorite color?: Red
PS C:\> $favColor
Red

Now you can see it didn't simply return Red to the console but captured it with the $favColor variable. At this point, we can add some logic in there to do different things based on that input.

if ($favColor -eq 'Red') {
    'My favorite too!'
} else {
    "Eww...$favColor is not a nice color!"
}
My favorite too!

Create a menu with the .NET ChoiceDescription class ^

Read-Host is versatile and can prompt for any text, but it doesn't look "official." It doesn't look like it is a part of PowerShell itself. For a more professional way of asking for input (multiple inputs), we can use the .NET ChoiceDescription object. This object allows us to define different options and then use a .NET method called PromptForChoice to display those options to the user.

This method of asking for input requires defining all the options ahead of time by creating multiple ChoiceDescription .NET objects. We then pass those objects to another .NET object that displays them in the console and asks the user to choose.

The .NET method that shows the options is called $host.ui.PromptForChoice(). This method requires four arguments to run: the title for the menu of options, the message to display, an array of System.Management.Automation.Host.ChoiceDescription objects, and a default choice if the user simply hits Enter.

First, we'll define all the options. Using the previous example, let's limit the number of favorite colors to Red, Blue, and Yellow. To do that, we'll have to create three objects each representing a choice.

$red = New-Object System.Management.Automation.Host.ChoiceDescription '&Red', 'Favorite color: Red'
$blue = New-Object System.Management.Automation.Host.ChoiceDescription '&Blue', 'Favorite color: Blue'
$yellow = New-Object System.Management.Automation.Host.ChoiceDescription '&Yellow', 'Favorite color: Yellow'

Once we've defined all the options, we'll group them all into an array.

$options = [System.Management.Automation.Host.ChoiceDescription[]]($red, $blue, $yellow)

Finally, we'll display them to the user, first defining the prompt title and message.

$title = 'Favorite color'
$message = 'What is your favorite color?'
$result = $host.ui.PromptForChoice($title, $message, $options, 0)

When run from the console, it'll then display a prompt that looks like it came from PowerShell itself.

Favorite color
What is your favorite color?
[R] Red  [B] Blue  [Y] Yellow  [?] Help (default is "R"):

And if you run the above code in PowerShell ISE, a graphical dialog box will appear:

Displaying an options menu with the ChoiceDescription class

The value of $result isn't the text specified; it's an index number starting at 0. So, for example, if you chose Red, the result would be 0, or if you chose Yellow, the value would be 2. You could make this distinction by using a switch statement to make a decision based on the input you provided.

switch ($result)
{
    0 { 'Your favorite color is Red' }
    1 { 'Your favorite color is Blue' }
    2 { 'Your favorite color is Yellow' }
}