Read-Host

模組:
Microsoft.PowerShell.Utility Module

讀取控制台的輸入線。

語法

AsString (預設值) 

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

AsSecureString 

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

Description

Read-Host指令檔會讀取來自主控台的一行輸入（stdin）。 你可以用它來提示使用者輸入意見。 因為你可以將輸入儲存為安全字串，你可以利用這個 cmdlet 提示使用者輸入安全資料，例如密碼。

Note

Read-Host 限制為 1022 個字元，可接受為使用者輸入。

範例

範例 1：將主控台輸入儲存為變數

此範例顯示字串「請輸入您的年齡」作為提示。 當輸入一個值並按下 Enter 鍵時，該值會被儲存在變數中 $Age 。

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

範例 2：將主控台輸入儲存為安全字串

此範例顯示字串「輸入密碼：」作為提示。 輸入值時，主控台上會以星號*（）取代輸入。 當按下 Enter 鍵時，該值會以 SecureString 物件的形式儲存在變數中 $pwd_secure_string 。

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

範例 3：遮罩輸入與明文字串

此範例顯示字串「輸入密碼：」作為提示。 輸入值時，主控台上會以星號*（）取代輸入。 按下 Enter 鍵時，該值會以明文 字串 物件的形式儲存在變數中 $pwd_string 。

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

範例 4：正規化輸入

此範例提示使用者輸入以分號分隔的城市列表。 它顯示使用者輸入的字串值。 在範例中，使用者在部分條目之間加了空格。 這可能導致腳本後續出現錯誤，程式碼會期待精確名稱。

這個範例展示了如何將輸入字串轉換成一個不加空格的條目陣列。

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

範例中使用 運算 -split 子將輸入字串轉換成字串陣列。 陣列中的每個字串都包含不同城市的名稱。 不過，分割弦包含額外的空格。 此 Trim() 方法移除每根弦的前置與後置空格。

參數

-AsSecureString

表示指令檔以星號*（）取代使用者輸入的字元。 使用此參數時，指令長的輸出 Read-Host 是一個 SecureString 物件（System.Security.SecureString）。

參數屬性

類型:SwitchParameter
預設值:None
支援萬用字元:False
不要顯示:False

參數集

AsSecureString
Position:Named
必要:False
來自管線的值:False
來自管線按屬性名稱的值:False
來自剩餘引數的值:False

-MaskInput

表示指令檔以星號*（）取代使用者輸入的字元。 當你使用這個參數時，指令小程式的輸出 Read-Host 會是一個 String 物件。 這讓你能安全地提示密碼，密碼會以明文回傳，而非 SecureString。

此參數是在 PowerShell 7.1 中加入的。

參數屬性

類型:SwitchParameter
預設值:None
支援萬用字元:False
不要顯示:False

參數集

AsString
Position:Named
必要:False
來自管線的值:False
來自管線按屬性名稱的值:False
來自剩餘引數的值:False

-Prompt

指定提示內容。 輸入一個字串。 若字串包含空格，則以引號包圍。 PowerShell 會在你輸入的文字後加上冒號:（）。

參數屬性

類型:Object
預設值:None
支援萬用字元:False
不要顯示:False

參數集

(All)
Position:0
必要:False
來自管線的值:False
來自管線按屬性名稱的值:False
來自剩餘引數的值:False

CommonParameters

此 cmdlet 支援常見參數：-Debug、-ErrorAction、-ErrorVariable、-InformationAction、-InformationVariable、-OutBuffer、-OutVariable、-PipelineVariable、-ProgressAction、-Verbose、-WarningAction 和 -WarningVariable。 如需詳細資訊，請參閱 about_CommonParameters。

輸入

None

您不能將物件透過管道傳送到此 Cmdlet。

輸出

String

預設情況下，此 cmdlet 會回傳一個字串。

SecureString

當你使用 AsSecureString 參數時，這個 cmdlet 會回傳一個 SecureString。

備註

此指令檔只讀取宿主程序的 stdin 串流。 通常，stdin 串流會連接到主機主控台的鍵盤。