ConvertFrom-StringData (Microsoft.PowerShell.Utility)

ConvertFrom-StringData

将包含一个或多个键值对的字符串转换为哈希表。

句法

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

描述

ConvertFrom-StringData cmdlet 将包含一个或多个键值对的字符串转换为哈希表。由于每个键值对必须位于单独的行上，因此这里经常使用字符串作为输入格式。默认情况下，键必须与值用等号(=)字符分隔。

ConvertFrom-StringData cmdlet 被认为是可以在脚本或函数的 DATA 部分中使用的安全 cmdlet。当在 DATA 部分中使用时，字符串的内容必须符合 DATA 部分的规则。有关详细信息，请参阅 about_Data_Sections。

ConvertFrom-StringData 支持传统机器翻译工具允许的转义字符序列。也就是说，cmdlet 可以使用 Regex.Unescape 方法将反斜杠 (\) 解释为字符串数据中的转义字符，而不是使用 PowerShell 反引号字符 (`)通常表示脚本中一行的结束。在此处字符串内，反引号字符不起作用。您还可以通过使用前面的反斜杠对其进行转义，从而在结果中保留文字反斜杠，如下所示：\。未转义的反斜杠字符（例如文件路径中常用的反斜杠字符）可能会在结果中呈现为非法转义序列。

PowerShell 7 添加了分隔符参数。

示例

示例 1：将单引号的此处字符串转换为哈希表

此示例将单引号的用户消息字符串转换为哈希表。在单引号字符串中，值不会替换变量，并且不会计算表达式。 ConvertFrom-StringData cmdlet 将 $Here 变量中的值转换为哈希表。

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

Name                           Value
----                           -----
Msg3                           The specified variable does not 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：转换包含注释的此处字符串

此示例将包含注释和多个键值对的此处字符串转换为哈希表。

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

# Category is optional.

Category = Storage
Cost = Free
'@

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

StringData 参数的值是此处字符串，而不是包含此处字符串的变量。任一格式均有效。这里的字符串包含有关其中一个字符串的注释。 ConvertFrom-StringData 忽略单行注释，但 # 字符必须是该行中的第一个非空白字符。 # 后面的行中的所有字符都将被忽略。

示例 4：将字符串转换为哈希表

此示例将常规双引号字符串（不是此处字符串）转换为哈希表并将其保存在 $A 变量中。

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

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

为了满足每个键值对必须位于单独的行上的条件，字符串使用 PowerShell 换行符 (`n) 来分隔键值对。

示例 5：在脚本的 DATA 部分使用 ConvertFrom-StringData

此示例显示了脚本的 DATA 部分中使用的 ConvertFrom-StringData 命令。 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 does not exist.
'@
$Hash = $Here | ConvertFrom-StringData
$Hash

Name     Value
----     -----
Msg3     The specified variable does not 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
        Did not 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 中添加的。

查尔

1

'='

False

False

False

-StringData

指定要转换的字符串。您可以使用此参数或通过管道将字符串传递给 ConvertFrom-StringData。参数名称是可选的。

该参数的值必须是包含一个或多个键值对的字符串。每个键值对必须位于单独的行上，或者每对必须用换行符 (`n) 分隔。

您可以在字符串中包含注释，但注释不能与键值对位于同一行。 ConvertFrom-StringData 忽略单行注释。 # 字符必须是该行中的第一个非空白字符。 # 后面的行中的所有字符都将被忽略。注释不包含在哈希表中。

Here-string 是由一行或多行组成的字符串。 Here-string 中的引号按字面意思解释为字符串数据的一部分。有关更多信息，请参阅 about_Quoting_Rules。

String

0

None

True

True

False

输入

字符串

您可以通过管道将包含键值对的字符串传递给此 cmdlet。

输出

哈希表

此 cmdlet 返回它根据键值对创建的哈希表。

笔记

Here-string 是由一行或多行组成的字符串，其中引号按字面解释。

此 cmdlet 在以多种口语显示用户消息的脚本中非常有用。您可以使用字典式哈希表将文本字符串与代码（例如资源文件中的代码）隔离，并设置文本字符串的格式以供翻译工具使用。