| external help file | Locale | Module Name | ms.date | online version | schema | title |
|---|---|---|---|---|---|---|
Microsoft.PowerShell.Commands.Utility.dll-Help.xml |
en-US |
Microsoft.PowerShell.Utility |
02/01/2022 |
2.0.0 |
Read-Host |
Read-Host
SYNOPSIS
Reads a line of input from the console.
SYNTAX
AsString (Default)
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-Hosthas a limit of 1022 characters it can accept as input from a user.
EXAMPLES
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" -AsSecureStringExample 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" -MaskInputPARAMETERS
-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).
Type: System.Management.Automation.SwitchParameter
Parameter Sets: AsSecureString
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: 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.
Type: System.Management.Automation.SwitchParameter
Parameter Sets: AsString
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: 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.
Type: System.Object
Parameter Sets: (All)
Aliases:
Required: False
Position: 0
Default value: None
Accept pipeline input: False
Accept wildcard characters: FalseCommonParameters
This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.
INPUTS
None
This cmdlet does not accept input from the PowerShell pipeline.
OUTPUTS
System.String or System.Security.SecureString
If the AsSecureString parameter is used, Read-Host returns a SecureString. Otherwise, it
returns a string.
NOTES
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.