Compartilhar via

Read-Host

Módulo:
Microsoft.PowerShell.Utility Module

Lê uma linha de entrada do console.

Sintaxe

AsString (Padrão) 

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

AsSecureString 

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 entrada a um 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 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 "Inserir uma Senha:" como um prompt. Como um valor está sendo inserido, os 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: Mascarar entrada e como uma cadeia de caracteres de texto sem formatação

Este exemplo exibe a cadeia de caracteres "Inserir uma Senha:" como um prompt. Como um valor está sendo inserido, os asteriscos (*) aparecem no console no lugar da entrada. Quando a tecla Enter é pressionada, o valor é armazenado como um objeto de cadeia de caracteres sem formatação 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 posteriormente 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 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).

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

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 retornada como texto sem formatação em vez de SecureString.

Esse parâmetro foi adicionado ao 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

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.

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

Este cmdlet suporta os parâmetros comuns: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction e -WarningVariable. Para obter mais informações, consulte about_CommonParameters.

Entradas

None

Não é possível transferir objetos para esse 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.

Observações

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