- Reference
- Module:
- Microsoft.PowerShell.Utility
Converts a string containing one or more key and value pairs to a hash table.
Syntax
ConvertFrom-StringData [-StringData] <String> [[-Delimiter] <Char>] [<CommonParameters>] Description
The ConvertFrom-StringData cmdlet converts a string that contains one or more key and value pairsinto a hash table. Because each key-value pair must be on a separate line, here-strings are oftenused as the input format. By default, the key must be separated from the value by an equalssign (=) character.
The ConvertFrom-StringData cmdlet is considered to be a safe cmdlet that can be used in theDATA section of a script or function. When used in a DATA section, the contents of thestring must conform to the rules for a DATA section. For more information, seeabout_Data_Sections.
ConvertFrom-StringData supports escape character sequences that are allowed by conventionalmachine translation tools. That is, the cmdlet can interpret backslashes (\) as escape charactersin the string data by using theRegex.Unescape Method, instead of thePowerShell backtick character (`) that would normally signal the end of a line in a script.Inside the here-string, the backtick character does not work. You can also preserve a literalbackslash in your results by escaping it with a preceding backslash, like this: \\. Unescapedbackslash characters, such as those that are commonly used in file paths, can render as illegalescape sequences in your results.
PowerShell 7 adds the Delimiter parameter.
Examples
Example 1: Convert a single-quoted here-string to a hash table
This example converts a single-quoted here-string of user messages into a hash table. In asingle-quoted string, values are not substituted for variables and expressions are not evaluated.The ConvertFrom-StringData cmdlet converts the value in the $Here variable to a hash table.
$Here = @'Msg1 = The string parameter is required.Msg2 = Credentials are required for this command.Msg3 = The specified variable does not exist.'@ConvertFrom-StringData -StringData $HereName Value---- -----Msg3 The specified variable does not exist.Msg2 Credentials are required for this command.Msg1 The string parameter is required.Example 2: Convert string data using a different delimiter
This example shows how to convert string data that uses a different character as a delimiter. Inthis example the string data is using the pipe character (|) as the delimiter.
$StringData = @'color|redmodel|coupeyear|1965condition|mint'@$carData = ConvertFrom-StringData -StringData $StringData -Delimiter '|'$carDataName Value---- -----condition mintmodel coupecolor redyear 1965Example 3: Convert a here-string containing a comment
This example converts a here-string that contains a comment and multiple key-value pairs into a hashtable.
ConvertFrom-StringData -StringData @'Name = Disks.ps1# Category is optional.Category = StorageCost = Free'@Name Value---- -----Cost FreeCategory StorageName Disks.ps1The value of the StringData parameter is a here-string, instead of a variable that contains ahere-string. Either format is valid. The here-string includes a comment about one of the strings.ConvertFrom-StringData ignores single-line comments, but the # character must be the firstnon-whitespace character on the line. All characters on the line after the # are ignored.
Example 4: Convert a string to a hash table
This example converts a regular double-quoted string (not a here-string) into a hash table and savesit in the $A variable.
$A = ConvertFrom-StringData -StringData "Top = Red `n Bottom = Blue"$AName Value---- -----Bottom BlueTop RedTo satisfy the condition that each key-value pair must be on a separate line, the string uses thePowerShell newline character (`n) to separate the pairs.
Example 5: Use ConvertFrom-StringData in the DATA section of a script
This example shows a ConvertFrom-StringData command used in the DATA section of a script.The statements below the DATA section display the text to the user.
$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.'@}$TextMsgsName 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.Because the text includes variable names, it must be enclosed in a single-quoted string so that thevariables are interpreted literally and not expanded. Variables are not permitted in the DATAsection.
Example 6: Use the pipeline operator to pass a string
This example shows that you can use a pipeline operator (|) to send a string toConvertFrom-StringData. The value of the $Here variable is piped to ConvertFrom-StringDataand the result in the $Hash variable.
$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$HashName Value---- -----Msg3 The specified variable does not exist.Msg2 Credentials are required for this command.Msg1 The string parameter is required.Example 7: Use escape characters to add new lines and return characters
This example shows the use of escape characters to create new lines and return characters in sourcedata. The escape sequence \n is used to create new lines within a block of text that is associatedwith a name or item in the resulting hash table.
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-ListName : AngeloValue : Let there be some more test made of my metal, Before so noble and so great a figure Be stamp'd upon it.Name : VincentioValue : 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.Example 8: Use backslash escape character to correctly render a file path
This example shows how to use of the backslash escape character in the string data to allow a filepath to render correctly in the resulting ConvertFrom-StringData hash table. The double backslashensures that the literal backslash characters render correctly in the hash table output.
ConvertFrom-StringData "Message=Look in c:\\Windows\\System32"Name Value---- -----Message Look in c:\Windows\System32Parameters
-Delimiter
The character used to separate the key from the value data in the string being converted.The default delimiter is the equals sign (=) character. This parameter was added in PowerShell 7.
| Type: | Char |
| Position: | 1 |
| Default value: | '=' |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-StringData
Specifies the string to be converted. You can use this parameter or pipe a string toConvertFrom-StringData. The parameter name is optional.
The value of this parameter must be a string that contains one or more key-value pairs. Eachkey-value pair must be on a separate line, or each pair must be separated by newline characters(`n).
You can include comments in the string, but the comments cannot be on the same line as a key-valuepair. ConvertFrom-StringData ignores single-line comments. The # character must be the firstnon-whitespace character on the line. All characters on the line after the # are ignored. Thecomments are not included in the hash table.
A here-string is a string consisting of one or more lines. Quotation marks within the here-stringare interpreted literally as part of the string data. For more information, seeabout_Quoting_Rules.
| Type: | String |
| Position: | 0 |
| Default value: | None |
| Required: | True |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
Inputs
String
You can pipe a string containing a key-value pair to this cmdlet.
Outputs
Hashtable
This cmdlet returns a hash table that it creates from the key-value pairs.
Notes
A here-string is a string consisting of one or more lines within which quotation marks areinterpreted literally.
This cmdlet can be useful in scripts that display user messages in multiple spoken languages. Youcan use the dictionary-style hash tables to isolate text strings from code, such as in resourcefiles, and to format the text strings for use in translation tools.
