ConvertFrom-StringData

模組:

Microsoft.PowerShell.Utility Module

將包含一或多個索引鍵和值組的字串轉換成哈希表。

語法

Default (預設值)

ConvertFrom-StringData
    [-StringData] <String>
    [[-Delimiter] <Char>]
    [<CommonParameters>]

Description

ConvertFrom-StringData Cmdlet 會將包含一或多個索引鍵和值組的字串轉換成哈希表。 由於每個鍵值對都必須位於各別行上，因此這裡字串通常作為輸入格式使用。 根據預設，索引鍵 必須與 值 以等號（=）字元分隔。

ConvertFrom-StringData Cmdlet 會被視為安全 Cmdlet，可用於腳本或函式的 data 區段。 在 data 區段中使用時，字串的內容必須符合 data 區段的規則。 如需詳細資訊，請參閱 about_Data_Sections。

ConvertFrom-StringData 支援傳統機器翻譯工具允許的逸出字元序列。 也就是說，Cmdlet 可以使用 \將反斜杠 （） 解譯為字串數據中的逸出字元，而不是通常表示腳本中行尾的 PowerShell 反引號字元 （`）。 在 here-string 內，反引號字元無法運作。 您也可以在結果中保留一個純文字的反斜杠，方法是用前面的反斜杠將其逸出，如下所示：\\。 未逸出的反斜杠字元，例如檔案路徑中常用的反斜杠字元，可以在結果中轉譯為不合法的逸出序列。

PowerShell 7 會新增 Delimiter 參數。

範例

範例 1：將單引號的 here-string 轉換成哈希表

此範例會將使用者訊息的單引號字串轉換成哈希表。 在單引號字串中，不會以變數取代值，而且不會評估表達式。 ConvertFrom-StringData Cmdlet 會將 $Here 變數中的值轉換成哈希表。

$Here = @'
Msg1 = The string parameter is required.
Msg2 = Credentials are required for this command.
Msg3 = The specified variable doesn't exist.
'@
ConvertFrom-StringData -StringData $Here

Name                           Value
----                           -----
Msg3                           The specified variable doesn't exist.
Msg2                           Credentials are required for this command.
Msg1                           The string parameter is required.

範例 2：使用不同的分隔符轉換字串數據

此範例示範如何將使用不同字元做為分隔符的字串數據進行轉換。 在此範例中，字串數據會使用管道字元 （|） 作為分隔符。

$StringData = @'
color|red
model|coupe
year|1965
condition|mint
'@
$carData = ConvertFrom-StringData -StringData $StringData -Delimiter '|'
$carData

Name                           Value
----                           -----
condition                      mint
model                          coupe
color                          red
year                           1965

範例 3：轉換包含批注的 here-string

此範例會將包含批注和多個索引鍵/值組的 here-string 轉換成哈希表。

ConvertFrom-StringData -StringData @'
Name = Disks.ps1

# Category is optional.

Category = Storage
Cost = Free
'@

Name                           Value
----                           -----
Cost                           Free
Category                       Storage
Name                           Disks.ps1

StringData 參數的值是 here-string，而不是包含 here-string 的變數。 任一格式都有效。 here-string 包含對其中一個字串的註解。 ConvertFrom-StringData 忽略單行批註，但哈希字元 （#） 必須是該行的第一個非空格符。

範例 4：將字串轉換成哈希表

本範例會將一般雙引號字串（而非here-string）轉換成哈希表，並將它儲存在 $A 變數中。

$A = ConvertFrom-StringData -StringData "Top = Red `n Bottom = Blue"
$A

Name             Value
----             -----
Bottom           Blue
Top              Red

為了滿足每個鍵值對必須位於個別行的條件，字串會使用 PowerShell 換行符 (`n) 來分隔鍵值對。

範例 5：在腳本的 'data' 區段中使用

此範例顯示文稿 ConvertFrom-StringData 區段中所使用的 data 命令。 data 區段下方的語句會顯示文字給使用者。

$TextMsgs = data {
ConvertFrom-StringData @'
Text001 = The $Notebook variable contains the name of the user's system notebook.
Text002 = The $MyNotebook variable contains the name of the user's private notebook.
'@
}
$TextMsgs

Name             Value
----             -----
Text001          The $Notebook variable contains the name of the user's system notebook.
Text002          The $MyNotebook variable contains the name of the user's private notebook.

因為文字包含變數名稱，所以它必須以單引號字串括住，以便以常值方式解譯變數，而不會展開變數。 data 區段中不允許變數。

範例 6：使用管線運算元傳遞字串

這個範例示範您可以使用管線運算子 （|） 將字串傳送至 ConvertFrom-StringData。 $Here 變數的值會透過管道傳送至 ConvertFrom-StringData，並將結果存入 $Hash 變數中。

$Here = @'
Msg1 = The string parameter is required.
Msg2 = Credentials are required for this command.
Msg3 = The specified variable doesn't exist.
'@
$Hash = $Here | ConvertFrom-StringData
$Hash

Name     Value
----     -----
Msg3     The specified variable doesn't exist.
Msg2     Credentials are required for this command.
Msg1     The string parameter is required.

範例 7：使用逸出字元新增行並傳回字元

這個範例示範如何使用逸出字元在源數據中建立新的行和傳回字元。 逸出序列 \n 用來在與結果哈希表中名稱或專案相關聯的文字區塊內建立新行。

ConvertFrom-StringData @"
Vincentio = Heaven doth with us as we with torches do,\nNot light them for themselves; for if our virtues\nDid not go forth of us, 'twere all alike\nAs if we had them not.
Angelo = Let there be some more test made of my metal,\nBefore so noble and so great a figure\nBe stamp'd upon it.
"@ | Format-List

Name  : Angelo
Value : Let there be some more test made of my metal,
        Before so noble and so great a figure
        Be stamp'd upon it.

Name  : Vincentio
Value : Heaven doth with us as we with torches do,
        Not light them for themselves; for if our virtues
        Didn't go forth of us, 'twere all alike
        As if we had them not.

範例 8：使用反斜杠逸出字元正確轉譯檔案路徑

這個範例示範如何使用字串數據中的反斜線轉義字元，讓檔案路徑在產生的 ConvertFrom-StringData 哈希表中正確顯示。 雙反斜杠可確保字面反斜杠字元在哈希表輸出中呈現正確。

ConvertFrom-StringData "Message=Look in C:\\Windows\\System32"

Name                           Value
----                           -----
Message                        Look in C:\Windows\System32

參數

-Delimiter

用來分隔 索引鍵 與所轉換字串中 值 數據的字元。 默認分隔符是等號 （=） 字元。 此參數已在PowerShell 7中新增。

參數屬性

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

參數集

(All)

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

-StringData

指定要轉換的字串。 您可以使用此參數或使用管道將字串傳送至 ConvertFrom-StringData。 參數名稱是選擇性的。

此參數的值必須是包含一或多個索引鍵/值組的字串。 每組鍵值對必須位於個別行上，或者每一組都必須以換行字元分隔（`n）。

您可以在字串中包含批註，但批注不能與索引鍵/值組位於同一行。 ConvertFrom-StringData 忽略單行注釋。 哈希字元 （#） 必須是行的第一個非空格符。 哈希字元 （#） 之後行上的所有字元都會被忽略。 批注不會包含在哈希表中。

here-string 是包含一或多行的字串。 此處字串內的引號會被直接解譯為字串內容的一部分。 如需詳細資訊，請參閱 about_Quoting_Rules。

參數屬性

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

參數集

(All)

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

CommonParameters

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

輸入

String

您可以使用管線將包含索引鍵/值組的字串傳送至此 Cmdlet。

輸出

Hashtable

此 Cmdlet 會傳回它從索引鍵/值組建立的哈希表。

備註

here-string 是由一或多行所組成的字串，其中引號會以字面方式解譯。

此 Cmdlet 在以多個口語語言顯示使用者訊息的腳本中很有用。 您可以使用字典樣式哈希表來隔離文字字串與程式代碼，例如在資源檔中，以及格式化文字字串以用於翻譯工具。