You want to use input from the user in your script.

To obtain user input, use the Read-Host cmdlet:

PS > $directory = Read-Host "Enter a directory name"
Enter a directory name: C:\MyDirectory
PS > $directory
C:\MyDirectory

The Read-Host cmdlet reads a single line of input from the user. If the input contains sensitive data, the cmdlet supports an –AsSecureString parameter to read this input as a SecureString.

If the user input represents a date, time, or number, be aware that most cultures represent these data types differently. For more information about writing culturally aware scripts, see the section called “Write Culture-Aware Scripts”.

For more information about the Read-Host cmdlet, type Get-Help Read-Host.

You want your script to get a single keypress from the user.

For most purposes, use the [Console]::ReadKey() method to read a key:

PS > $key = [Console]::ReadKey($true)
PS > $key

                 KeyChar                   Key              Modifiers
                 -------                   ---              ---------
                       h                     H                    Alt

For highly interactive use (for example, when you care about key down and key up), use:

PS > $key = $host.UI.RawUI.ReadKey("NoEcho,IncludeKeyDown")
PS > $key

    VirtualKeyCode          Character    ControlKeyState      KeyDown
    --------------          ---------    ---------------      -------
                16                    ...ssed, NumLockOn         True

PS > $key.ControlKeyState
ShiftPressed, NumLockOn

For most purposes, the [Console]::ReadKey() is the best way to get a keystroke from a user, as it accepts simple keypresses—as well as more complex keypresses that might include the Ctrl, Alt, and Shift keys. We pass the $true parameter to tell the method to not display the character on the screen, and only to return it to us.

The following function emulates the DOS pause command:

function Pause
{
    Write-Host -NoNewLine "Press any key to continue . . . "
    [Console]::ReadKey($true) | Out-Null
    Write-Host
}

If you need to capture individual key down and key up events (including those of the Ctrl, Alt, and Shift keys), use the $host.UI.RawUI.ReadKey() method.

You want to display messages and other information to the user.

To ensure that the output actually reaches the screen, call the Write-Host (or Out-Host) cmdlet:

PS > function Get-DirectorySize
>> {
>>     $size = (Get-ChildItem | Measure-Object -Sum Length).Sum
>>     Write-Host ("Directory size: {0:N0} bytes" -f $size)
>> }
>>
PS > Get-DirectorySize
Directory size: 46,581 bytes
PS > $size = Get-DirectorySize
Directory size: 46,581 bytes

If you want a message to help you (or the user) diagnose and debug your script, use the Write-Debug cmdlet. If you want a message to provide detailed trace-type output, use the Write-Verbose cmdlet, as shown in Example 13.2, “A function that provides debug and verbose output”.

PS > function Get-DirectorySize
>> {
>>     Write-Debug "Current Directory: $(Get-Location)"
>>
>>     Write-Verbose "Getting size"
>>     $size = (Get-ChildItem | Measure-Object -Sum Length).Sum
>>     Write-Verbose "Got size: $size"
>>
>>     Write-Host ("Directory size: {0:N0} bytes" -f $size)
>> }
>>
PS > $DebugPreference = "Continue"
PS > Get-DirectorySize
DEBUG: Current Directory: D:\lee\OReilly\Scripts\Programs
Directory size: 46,581 bytes
PS > $DebugPreference = "SilentlyContinue"
PS > $VerbosePreference = "Continue"
PS > Get-DirectorySize
VERBOSE: Getting size
VERBOSE: Got size: 46581
Directory size: 46,581 bytes
PS > $VerbosePreference = "SilentlyContinue"

Most scripts that you write will output richly structured data, such as the actual count of bytes in a directory. That way, other scripts can use the output of that script as a building block for their functionality.

When you do want to provide output specifically to the user, use the Write-Host, Write-Debug, and Write-Verbose cmdlets.

However, be aware that this type of output bypasses normal file redirection, and is therefore difficult for the user to capture. In the case of the Write-Host cmdlet, use it only when your script already generates other structured data that the user would want to capture in a file or variable.

Most script authors eventually run into the problem illustrated by Example 13.3, “An error message caused by formatting statements” when their script tries to output formatted data to the user.

PS > ## Get the list of items in a directory, sorted by length
PS > function Get-ChildItemSortedByLength($path = (Get-Location))
>> {
>>     Get-ChildItem $path | Format-Table | Sort Length
>> }
>>
PS > Get-ChildItemSortedByLength
out-lineoutput : Object of type "Microsoft.PowerShell.Commands.Internal.Fo
rmat.FormatEntryData" is not legal or not in the correct sequence. This is
likely caused by a user-specified "format-*" command which is conflicting
with the default formatting.

This happens because the Format-* cmdlets actually generate formatting information for the Out-Host cmdlet to consume. The Out-Host cmdlet (which PowerShell adds automatically to the end of your pipelines) then uses this information to generate formatted output. To resolve this problem, always ensure that formatting commands are the last commands in your pipeline, as shown in Example 13.4, “A function that does not generate formatting errors”.

PS > ## Get the list of items in a directory, sorted by length
PS > function Get-ChildItemSortedByLength($path = (Get-Location))
>> {
>>     ## Problematic version
>>     ## Get-ChildItem $path | Format-Table | Sort Length
>>
>>     ## Fixed version
>>     Get-ChildItem $path | Sort Length | Format-Table
>> }
>>
PS > Get-ChildItemSortedByLength

(...)

Mode                LastWriteTime     Length Name
----                -------------     ------ ----
-a---         3/11/2007   3:21 PM         59 LibraryProperties.ps1
-a---          3/6/2007  10:27 AM        150 Get-Tomorrow.ps1
-a---          3/4/2007   3:10 PM        194 ConvertFrom-FahrenheitWithout
                                             Function.ps1
-a---          3/4/2007   4:40 PM        257 LibraryTemperature.ps1
-a---          3/4/2007   4:57 PM        281 ConvertFrom-FahrenheitWithLib
                                             rary.ps1
-a---          3/4/2007   3:14 PM        337 ConvertFrom-FahrenheitWithFunc
                                             tion.ps1
(...)

When it comes to producing output for the user, a common reason is to provide progress messages. PowerShell actually supports this in a much richer way, through its Write-Progress cmdlet. For more information about the Write-Progress cmdlet, see the section called “Provide Progress Updates on Long-Running Tasks”.

You want to display status information to the user for long-running tasks.

To provide status updates, use the Write-Progress cmdlet as shown in Example 13.5, “Using the Write-Progress cmdlet to display status updates”.

$activity = "A long running operation"

$status = "Initializing"
for($counter = 0; $counter -lt 100; $counter++)
{
    $currentOperation = "Initializing item $counter"
    Write-Progress $activity $status -PercentComplete $counter `
                   -CurrentOperation $currentOperation
    Start-Sleep -m 20
}

$status = "Running"
for($counter = 0; $counter -lt 100; $counter++)
{
    $currentOperation = "Running task $counter"
    Write-Progress $activity $status -PercentComplete $counter `
                   -CurrentOperation $currentOperation
    Start-Sleep -m 20
}
      

The Write-Progress cmdlet provides a way for you to provide structured status information to the users of your script for long-running operations (see Figure 13.1, “Example output from a long-running operation”).

Like the other detailed information channels (Write-Debug, Write-Verbose, and the other Write-* cmdlets), PowerShell lets users control how much of this information they see.

For more information about the Write-Progress cmdlet, type Get-Help Write-Progress.

Figure 13.1. Example output from a long-running operation

You want to ensure that your script works well on computers around the world.

To write culture-aware scripts, keep the following guidelines in mind as you develop your scripts:

Writing culture-aware programs has long been isolated to the world of professional software developers. It's not that users of simple programs and scripts can't benefit from culture awareness though. It has just frequently been too difficult for non-professional programmers to follow the best practices. PowerShell makes this much easier than traditional programming languages however.

As your script travels between different cultures, several things change.

$userInput = Read-Host "Please enter a date"
$enteredDate = [DateTime]::Parse($userInput)

## $text comes from the user, and contains the value "quit"
if($text.ToUpper() -eq "QUIT") { ... }

PS > $text1 = "Hello"
PS > $text2 = "HELLO"
PS > $text1 -eq $text2
True

PS > Use-Culture en-US { "Apple","Æble" | Sort-Object }
Æble
Apple
PS > Use-Culture da-DK { "Apple","Æble" | Sort-Object }
Apple
Æble

You are displaying text messages to the user, and want to support international languages.

Use the Import-LocalizedData cmdlet, as shown inExample 13.6, “Importing culture-specific strings for a script or module”.

## Create some default messages for English cultures, and
$messages = DATA {
    @{
        Greeting = "Hello, {0}"
        Goodbye = "So long."
    }
}

Import-LocalizedData messages -ErrorAction SilentlyContinue

$messages.Greeting -f "World"
$messages.Goodbye      

The Import-LocalizedData cmdlet lets you easily write scripts that display different messages for different languages.

The core of this localization support comes from the concept of a message table: a simple mapping of message IDs (such as a "Greeting" or "Goodbye" message) to the actual message it represents. Instead of directly outputting a string to the user, you instead retrieve the string from the message table and output that. Localization of your script comes from replacing the message table with one that contains messages appropriate for the current language.

PowerShell uses standard hashtables to define message tables. Keys and values in the hashtable represent message IDs their corresponding strings, respectively.

After defining a default message table in your script, the next step is to create localized versions and place them in language-specific directories alongside your script. The real magic of the Import-LocalizedData cmdlet comes from the intelligence it applies when loading the appropriate message file.

As a background, the standard way to refer to a culture (for localization purposes) is an identifier that combines the culture and region. For example, German as spoken in Germany is defined by the identifier de-DE. English as spoken in the United States is defined by the identifier en-US, while English as spoken in Canada is defined by the identifier en-CA. Most languages are spoken in many regions.

When you call the Import-LocalizedData cmdlet, PowerShell goes to the same directory as your script, and first tries to load your messages from a directory with a name that matches the full name of the current culture (for example, en-CA or en-GB.) If that fails, it falls back to the region-neutral directory (such as en, or de) and on to the other fallback languages defined by the operating system.

To make your efforts available to the broadest set of languages, place your localized messages in the most general directory that applies. For example, place French messages (first) in the "fr" directory so that all French-speaking regions can benefit. If you want to customize your messages to a specific region after that, place them in a region-specific directory.

Rather than define these message tables in script files (like your main script), place them in .psd1 files that have the same name as your script. For example, Example 13.6, “Importing culture-specific strings for a script or module” places its localized messages in Import-LocalizedData.psd1. PowerShell's psd1 files represent a data-centric subset of the full PowerShell language, and are ideally suited for localization. In the .psd1 file, define a hashtable—but do not store it in a variable like you do for the default message table:

@{
    Greeting = "Guten Tag, {0}"
    Goodbye = "Auf Wiedersehen."
}      

If you already use a set of tools to help you manage the software localization process, they may not understand the PowerShell .psd1 file format. Another standard message format is simple name-value mapping, so PowerShell supports that through the ConvertFrom-StringData cmdlet:

ConvertFrom-StringData @'
Greeting = Guten Tag, {0}
Goodbye = Auf Wiedersehen
'@

Notice that the Greeting message in Example 13.6, “Importing culture-specific strings for a script or module” uses {0}-style placeholders (and PowerShell's string formatting operator) to output strings with replacable text. This technique is vastly preferred over string concatenation (i.e.: $messages.GreetingBeforeName + " World " + $messages.GreetingAftername) because it gives additional flexibility during localization of languages with different sentence structure.

To test your script under different languages, you can use the section called “Program: Invoke a Script Block with Alternate Culture Settings”.

PS > Use-Culture de-DE { Invoke-LocalizedScript }
Guten Tag, World
Auf Wiedersehen.

For more information about script internationalization, type Get-Help about_Script_Internationalization.

You want to interact with features in the user interface of the hosting application, but PowerShell doesn't directly provide cmdlets for them.

To access features of the host's user interface, use the $host.UI.RawUI variable:

$host.UI.RawUI.WindowTitle = (Get-Location)

PowerShell itself consists of two main components. The first is an engine that interprets commands, executes pipelines, and performs other similar actions. The second is the hosting application—the way that users interact with the PowerShell engine.

The default shell, PowerShell.exe, is a user interface based on the traditional Windows console. The graphical Integrated Scripting Environment hosts PowerShell in a graphical user interface. In fact, PowerShell makes it relatively simple for developers to build their own hosting applications, or even to embed the PowerShell engine features into their own application.

You (and your scripts) can always depend on the functionality available through the $host.UI variable, as that functionality remains the same for all hosts. Example 13.9, “Functionality available through the $host.UI property” shows the features available to you in all hosts.

PS > $host.UI | Get-Member | Select Name,MemberType | Format-Table -Auto

Name                   MemberType
----                   ----------
(...)
Prompt                     Method
PromptForChoice            Method
PromptForCredential        Method
ReadLine                   Method
ReadLineAsSecureString     Method
Write                      Method
WriteDebugLine             Method
WriteErrorLine             Method
WriteLine                  Method
WriteProgress              Method
WriteVerboseLine           Method
WriteWarningLine           Method
RawUI                    Property

If you (or your scripts) want to interact with portions of the user interface specific to the current host, PowerShell provides that access through the $host.UI.RawUI variable. Example 13.10, “Functionality available through the default console host” shows the features available to you in the PowerShell console host.

PS > $host.UI.RawUI | Get-Member |
>>     Select Name,MemberType | Format-Table -Auto
>>

Name                      MemberType
----                      ----------
(...)
FlushInputBuffer              Method
GetBufferContents             Method
GetHashCode                   Method
GetType                       Method
LengthInBufferCells           Method
NewBufferCellArray            Method
ReadKey                       Method
ScrollBufferContents          Method
SetBufferContents             Method
BackgroundColor             Property
BufferSize                  Property
CursorPosition              Property
CursorSize                  Property
ForegroundColor             Property
KeyAvailable                Property
MaxPhysicalWindowSize       Property
MaxWindowSize               Property
WindowPosition              Property
WindowSize                  Property
WindowTitle                 Property

If you rely on the host-specific features from $host.UI.RawUI, be aware that your script will require modifications (perhaps major) before it will run properly on other hosts.

You want to interact with a user interface framework or other object that requires that the current thread be in Single Threaded Apartment (STA) mode:

PS > Add-Type -Assembly PresentationCore
PS > [Windows.Clipboard]::SetText("Hello World")
Exception calling "SetText" with "1" argument(s): "Current thread must be
set to single thread apartment (STA) mode before OLE calls can be made."
At line:1 char:29
+ [Windows.Clipboard]::SetText <<<< ("Hello World")
    + CategoryInfo          : NotSpecified: (:) [], MethodInvocationExcep
   tion
    + FullyQualifiedErrorId : DotNetMethodException

Launch PowerShell with the -STA switch. If you do this as part of a script or helper command, also use the -NoProfile switch to avoid the performance impact and side effects of loading the user's profile:

PS > PowerShell -NoProfile -STA -Command {
>>     Add-Type -Assembly PresentationCore
>>     [Windows.Clipboard]::SetText("Hello World")
>> }
>>
PS > PowerShell -NoProfile -STA -Command {
>>     Add-Type -Assembly PresentationCore
>>     [Windows.Clipboard]::GetText()
>> }
>>
Hello World

Threading modes define an agreement between an application and how it interacts with some of its objects. Most objects in the .NET Framework (and thus, PowerShell and nearly everything it interacts with) ignore the threading mode and are not impacted by it.

Many user interface frameworks (such as WPF and WinForms) do require a specific threading mode, though, called Single Threaded Apartment. PowerShell uses a threading mode called Multi-Threaded Apartment (MTA) by default, so you'll sometimes run into an error similar to that in the problem

If you frequently find yourself needing to use STA mode, you can simply modify the PowerShell link on your start menu to always load PowerShell with the -STA parameter. It is incredibly rare for a component to requre MTA mode rather than STA mode, and it has no performance impact.

If your entire script requires STA mode, you have two primary options: detect the current threading mode, or relaunch yourself under STA mode.

To detect the current threading mode, you can access the $host.Runspace.ApartmentState variable. If its value is "STA", the current threading mode is STA.

If your script has simple parameter requirements, you may be able to relaunch yourself automatically:

###########################################################################

param(
    $parameter1,
    $parameter2
)

"Current threading mode: " + $host.Runspace.ApartmentState
"Parameter1 is: $parameter1"
"Parameter2 is: $parameter2"

if($host.Runspace.ApartmentState -ne "STA")
{
    "Relaunching"
    $file = $myInvocation.MyCommand.Path
    powershell -NoProfile -Sta -File $file $parameter1 $parameter2
    return
}

"After relaunch - current threading mode: " + $host.Runspace.ApartmentState      

When you run this script, you get the following output:

PS > .\Invoke-ScriptThatRequiresSta.ps1 Test1 Test2
Current threading mode: Unknown
Parameter1 is: Test1
Parameter2 is: Test2
Relaunching
Current threading mode: STA
Parameter1 is: Test1
Parameter2 is: Test2
After relaunch - current threading mode: STA