Compartilhar via

Read-Host

Módulo:
Microsoft.PowerShell.Utility Module

Reads a line of input from the console.

Sintaxe

AsString (Padrão) 

Read-Host
    [[-Prompt] <Object>]
    [-MaskInput]
    [<CommonParameters>]

AsSecureString 

Read-Host
    [[-Prompt] <Object>]
    [-AsSecureString]
    [<CommonParameters>]

Description

The Read-Host cmdlet reads a line of input from the console (stdin). You can use it to prompt a user for input. Because you can save the input as a secure string, you can use this cmdlet to prompt users for secure data, such as passwords.

Note

Read-Host has a limit of 1022 characters it can accept as input from a user.

Exemplos

Example 1: Save console input to a variable

This example displays the string "Please enter your age:" as a prompt. When a value is entered and the Enter key is pressed, the value is stored in the $Age variable.

$Age = Read-Host "Please enter your age"

Example 2: Save console input as a secure string

This example displays the string "Enter a Password:" as a prompt. As a value is being entered, asterisks (*) appear on the console in place of the input. When the Enter key is pressed, the value is stored as a SecureString object in the $pwd_secure_string variable.

$pwd_secure_string = Read-Host "Enter a Password" -AsSecureString

Example 3: Mask input and as a plaintext string

This example displays the string "Enter a Password:" as a prompt. As a value is being entered, asterisks (*) appear on the console in place of the input. When the Enter key is pressed, the value is stored as a plaintext String object in the $pwd_string variable.

$pwd_string = Read-Host "Enter a Password" -MaskInput

Example 4: Normalizing input

This example prompts the user to input a list of cities separated by semi-colons. It shows the string's value as typed by the user. In the example, the user added spaces between some of the entries. This could lead to an error later in the script where the code expects an exact name.

The example shows how you can convert an input string into an array of entries without any extra spaces.

$prompt = @(
    'List the cities you want weather information for.'
    'When specifying multiple cities, separate them with a semi-colon, like:'
    "'New York; Osan; Koforidua'"
) -join ' '

$cities = Read-Host $prompt

"Input cities string: `n`t'$cities'"

$splitCities = $cities -split ';'

"Split cities array:"
$splitCities | ForEach-Object -Process { "`t'$_'" }

$normalizedCities = $splitCities  | ForEach-Object -Process { $_.Trim() }

"Normalized split cities array:"
$normalizedCities | ForEach-Object -Process { "`t'$_'" }

Input cities string:
        '    New York;  Osan   ;Koforidua   '
Split cities array:
        '    New York'
        '  Osan   '
        'Koforidua   '
Normalized split cities array:
        'New York'
        'Osan'
        'Koforidua'

The example uses the -split operator to convert the input string into an array of strings. Each string in the array includes the name of a different city. However, the split strings include extra spaces. The Trim() method removes the leading and trailing spaces from each string.

Parâmetros

-AsSecureString

Indicates that the cmdlet displays asterisks (*) in place of the characters that the user types as input. When you use this parameter, the output of the Read-Host cmdlet is a SecureString object (System.Security.SecureString).

Propriedades do parâmetro

Tipo:SwitchParameter
Valor padrão:None
Dá suporte a curingas:False
DontShow:False

Conjuntos de parâmetros

AsSecureString
Cargo:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline pelo nome da propriedade:False
Valor dos argumentos restantes:False

-MaskInput

Indicates that the cmdlet displays asterisks (*) in place of the characters that the user types as input. When you use this parameter, the output of the Read-Host cmdlet is a String object. This allows you to safely prompt for a password that is returned as plaintext instead of SecureString.

This parameter was added in PowerShell 7.1.

Propriedades do parâmetro

Tipo:SwitchParameter
Valor padrão:None
Dá suporte a curingas:False
DontShow:False

Conjuntos de parâmetros

AsString
Cargo:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline pelo nome da propriedade:False
Valor dos argumentos restantes:False

-Prompt

Specifies the text of the prompt. Type a string. If the string includes spaces, enclose it in quotation marks. PowerShell appends a colon (:) to the text that you enter.

Propriedades do parâmetro

Tipo:Object
Valor padrão:None
Dá suporte a curingas:False
DontShow:False

Conjuntos de parâmetros

(All)
Cargo:0
Obrigatório:False
Valor do pipeline:False
Valor do pipeline pelo nome da propriedade:False
Valor dos argumentos restantes:False

CommonParameters

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.

Entradas

None

You can't pipe objects to this cmdlet.

Saídas

String

By default, this cmdlet returns a string.

SecureString

When you use AsSecureString parameter, this cmdlet returns a SecureString.

Observações

This cmdlet only reads from the stdin stream of the host process. Usually, the stdin stream is connected to the keyboard of the host console.