Read-Host

  • Referência
Módulo:
Microsoft.PowerShell.Utility

Lê uma linha de entrada do console.

Syntax

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

Description

O Read-Host cmdlet lê uma linha de entrada do console (stdin). Você pode usá-lo para solicitar uma entrada do usuário. Como você pode salvar a entrada como uma cadeia de caracteres segura, você pode usar esse cmdlet para solicitar aos usuários dados seguros, como senhas.

Observação

Read-Host tem um limite de 1022 caracteres que pode aceitar como entrada de um usuário.

Exemplos

Exemplo 1: Salvar a entrada do console em uma variável

Este exemplo exibe a cadeia de caracteres "Insira sua idade:" como um prompt. Quando um valor é inserido e a tecla Enter é pressionada, o valor é armazenado na $Age variável.

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

Exemplo 2: Salvar a entrada do console como uma cadeia de caracteres segura

Este exemplo exibe a cadeia de caracteres "Enter a Password:" como um prompt. À medida que um valor está sendo inserido, asteriscos (*) aparecem no console no lugar da entrada. Quando a tecla Enter é pressionada, o valor é armazenado como um objeto SecureString na $pwd_secure_string variável.

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

Exemplo 3: Entrada de máscara e como uma cadeia de caracteres de texto sem formatação

Este exemplo exibe a cadeia de caracteres "Enter a Password:" como um prompt. À medida que um valor está sendo inserido, asteriscos (*) aparecem no console no lugar da entrada. Quando a tecla Enter é pressionada, o valor é armazenado como um objeto String de texto sem formatação na $pwd_string variável.

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

Exemplo 4: Normalizando a entrada

Este exemplo solicita que o usuário insira uma lista de cidades separadas por ponto-e-vírgula. Ele mostra o valor da cadeia de caracteres conforme digitado pelo usuário. No exemplo, o usuário adicionou espaços entre algumas das entradas. Isso pode levar a um erro mais tarde no script em que o código espera um nome exato.

O exemplo mostra como você pode converter uma cadeia de caracteres de entrada em uma matriz de entradas sem espaços extras.

$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'

O exemplo usa o -split operador para converter a cadeia de caracteres de entrada em uma matriz de cadeias de caracteres. Cada cadeia de caracteres na matriz inclui o nome de uma cidade diferente. No entanto, as cadeias de caracteres divididas incluem espaços extras. O Trim() método remove os espaços à esquerda e à direita de cada cadeia de caracteres.

Parâmetros

-AsSecureString

Indica que o cmdlet exibe asteriscos (*) no lugar dos caracteres que o usuário digita como entrada. Quando você usa esse parâmetro, a Read-Host saída do cmdlet é um objeto SecureString (System.Security.SecureString).

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-MaskInput

Indica que o cmdlet exibe asteriscos (*) no lugar dos caracteres que o usuário digita como entrada. Quando você usa esse parâmetro, a Read-Host saída do cmdlet é um objeto String . Isso permite que você solicite com segurança uma senha que é retornada como texto sem formatação em vez de SecureString.

Esse parâmetro foi adicionado no PowerShell 7.1.

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Prompt

Especifica o texto do aviso. Digite uma cadeia de caracteres. Se a cadeia de caracteres incluir espaços, coloque-a entre aspas. O PowerShell acrescenta dois pontos (:) ao texto inserido.

Type:Object
Position:0
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

Entradas

None

Não é possível canalizar objetos para esse cmdlet.

Saídas

String

Por padrão, esse cmdlet retorna uma cadeia de caracteres.

SecureString

Quando você usa o parâmetro AsSecureString , esse cmdlet retorna um SecureString.

Observações

Esse cmdlet só lê o fluxo stdin do processo do host. Normalmente, o fluxo stdin é conectado ao teclado do console host.