Partilhar via

Read-Host

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

Lê uma linha de entrada do console.

Sintaxe

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

Description

O cmdlet Read-Host lê uma linha de entrada do console (stdin). Você pode usá-lo para solicitar a entrada de um usuário. Como você pode salvar a entrada como uma cadeia de caracteres segura, 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 "Please enter your age:" como um prompt. Quando um valor é inserido e a tecla Enter é pressionada, o valor é armazenado na variável $Age.

$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 é inserido, asteriscos (*) aparecem no console no lugar da entrada. Quando a tecla Enter é pressionada, o valor é armazenado como um objeto SecureString na variável $pwd_secure_string.

$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 é inserido, asteriscos (*) aparecem no console no lugar da entrada. Quando a tecla Enter é pressionada, o valor é armazenado como um texto sem formatação objeto String na variável $pwd_string.

$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, onde 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 operador -split 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 método Trim() 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 saída do cmdlet Read-Host é um objeto SecureString (System.Security.SecureString).

Tipo:SwitchParameter
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais: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 saída do cmdlet Read-Host é um objeto String. Isso permite que você solicite com segurança uma senha que é retornada como texto sem formatação em vez de SecureString.

Este parâmetro foi adicionado no PowerShell 7.1.

Tipo:SwitchParameter
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-Prompt

Especifica o texto do prompt. 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.

Tipo:Object
Position:0
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

Entradas

None

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

Saídas

String

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

SecureString

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

Notas

Este cmdlet só lê a partir do fluxo stdin do processo de host. Normalmente, o fluxo stdin está conectado ao teclado do console host.