ConvertFrom-StringData

模块:

Microsoft.PowerShell.Utility

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

语法

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

说明

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

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

ConvertFrom-StringData 支持传统机器翻译工具允许的转义字符序列。 也就是说，cmdlet 可以使用 Regex.Unescape 方法将反斜杠解释为字符串数据中的转义字符 (\) ，而不是 PowerShell 反斜杠字符 (') ，该字符通常会在脚本中发出行尾信号。 在 here-string 中，反撇号字符无效。 还可以通过在前面的反斜杠中转义文本反斜杠来保留结果中的文本反斜杠，如下所示： \\ 未转义的反斜杠字符（例如那些通常用在文件路径中的反斜杠字符）可以在结果中呈现为非法的转义序列。

示例

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

本示例将用户消息的单引号字符串转换为哈希表。 在带单引号的字符串中，不能使用变量和无法计算的表达式来代替其值。 该 cmdlet 将 ConvertFrom-StringData 变量中的 $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：转换包含注释的此处字符串

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

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 包括有关某字符串的注释。 ConvertFrom-StringData 忽略单行注释，但 # 字符必须是行上的第一个非空格字符。 忽略行后 # 的所有字符。

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

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

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

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

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

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

此示例演示 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 节中不允许变量。

示例 5：使用管道运算符传递字符串

此示例演示如何使用管道运算符 (|) 将字符串 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.

示例 6：使用转义字符添加新行并返回字符

此示例演示如何使用转义字符创建新行并在源数据中返回字符。 转义序列 \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.

示例 7：使用反斜杠转义字符正确呈现文件路径

此示例演示如何使用字符串数据中的反斜杠转义字符，以允许文件路径在生成的 ConvertFrom-StringData 哈希表中正确呈现。 双反斜杠可确保文本反斜杠字符正确呈现在哈希表输出中。

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

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

参数

-StringData

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

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

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

此处的字符串是由一行或多行组成的字符串。 此处字符串中的引号将字面解释为字符串数据的一部分。 有关详细信息，请参阅 about_Quoting_Rules。

Type:	String
Position:	0
Default value:	None
Required:	True
Accept pipeline input:	True
Accept wildcard characters:	False

输入

String

可以通过管道将包含键值对的字符串传递给 ConvertFrom-StringData。

输出

Hashtable

此 cmdlet 返回从键值对创建的哈希表。

备注

here-string 是由一行或多行组成的字符串，在其中，按照字义解释引号。

此 cmdlet 在显示多种语言的用户消息的脚本中非常有用。 可使用字典风格的哈希表来从代码中隔离文本字符串（如在资源文件中），并为文本字符串设置格式以便在转换工具中使用。