Prompts the user to select a choice.

Read-PromptForChoice.ps1

#requires -Version 4.0

function Read-PromptForChoice
{
    <#
    .SYNOPSIS
        Prompts the user to select a choice.
    
    .DESCRIPTION
        Given a title, message, and ordered hashtable of options Read-PromptForChoice will call the 
        PromptForChoice method of the PSHostUserInterface class. This provides a uniform and friendly 
        experience when you have a need to prompt the user to interactively make a decision in response 
        to actions carried out in script.
    
    .NOTES
        Author   : Lido Paglia <lido@paglia.org>
        Date     : 01/25/2014 21:20:49
        
    .PARAMETER Title
        The text to display preceeding the choice. In the ISE this title is displayed in the window title.

    .PARAMETER Message
        Some text that describes the choice. This is secondary to the title. In the ISE this text appears 
        as the message box text.
    
    .PARAMETER Options
        A collection of options specified as an ordered hashtable. The object supplied to the Options parameter
        must be an Ordered hash table. The 'Name' value is the text displayed on the menu button in the ISE or the 
        full option text in the Console Host. The 'Value' corresponds to the help message text for each supplied option. 
        This help text can be accessed in the shell by typing [?] for help or in the ISE by hovering over the button choice.
    
    .INPUTS
        None. You cannot pipe objects to Read-PromptForChoice.
    
    .OUTPUTS
        System.Int32. Read-PromptForChoice returns an integer value corresponding to the order of menu options provided.
    
    .EXAMPLE
        Read-PromptForChoice -Title "Hi, I'm a Title" -Message "This is the message." -Options ([ordered]@{Yes='You know you want to.';No='Just say no.'})

    .EXAMPLE
        $PromptParams = @{
            Title   = "WARNING: Uneven Names"
            Message = "The list of names are uneven. Want to pick a name to use more than once?"
            Options = ([ordered]@{
                Yes = "Select someone to use more than once."
                No  = "Quit."
            })
        }

        $result = Read-PromptForChoice @PromptParams

        switch ($result)
        {
            0 {$Dupe = $Names | Out-GridView -Outputmode Single}
            1 {return}
        }
    
    .EXAMPLE
        [scriptblock]$sb = {Get-Process}

        $PromptParams = @{
            Title   = "List running Services or Processes"
            Message = "Want to run Get-Service or Get-Process?"
            Options = ([ordered]@{
                Service  = "execute Get-Service"
                Process  = "execute Get-Process"
                Cancel   = "Quit"
            })
        }

        $result = Read-PromptForChoice @PromptParams

        switch ($result)
        {
            0 {Get-Service}
            1 {Invoke-Command $sb}
            2 {return}
        } 

    .LINK
         http://msdn.microsoft.com/en-us/library/system.management.automation.host.pshostuserinterface.promptforchoice(v=vs.85).aspx
    
    #>

    Param(
        [string]$Title,
        [string]$Message,
        [Collections.Specialized.OrderedDictionary]$Options
    )
    
    $varOptions = @()

    $Options.GetEnumerator() | foreach {

        $varParams = @{
            Name  = $_.Name
            Value = (New-Object System.Management.Automation.Host.ChoiceDescription "&$($_.Name)", "$($_.Value)")
        }

        $varOptions += @(New-Variable @varParams -PassThru -Force)
    }
    
    $Host.UI.PromptForChoice($title, $message, ($varOptions.GetEnumerator().Value), 0)

}