ConvertFrom-StringData

Specifies the string to be converted. You can use this parameter or pipe a string to ConvertFrom-StringData. The parameter name is optional.

The value of this parameter must be a string that is enclosed in single quotation marks (a single-quoted string) or a string that is enclosed in double quotation marks (a double-quoted string) or a here-string containing one or more key/value pairs. Each key/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/value pair. The comments are not included in the hash table.

A here-string is a string consisting of one or more lines within which quotation marks are interpreted literally. For more information, see about_Quoting_Rules.

This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see  about_CommonParameters (http://go.microsoft.com/fwlink/p/?LinkID=113216).

These commands convert a single-quoted here-string of user messages into a hash table. In a single-quoted string, values are not substituted for variables and expressions are not evaluated.

The first command creates a here-string and saves it in the $here variable.

The second command uses the ConvertFrom-StringData cmdlet to convert the here-string in the $here variable to a hash table.

PS C:\> $here = @'Msg1 = The string parameter is required.Msg2 = Credentials are required for this command.Msg3 = The specified variable does not exist.'@PS C:\>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.

These commands demonstrate that ConvertFrom-StringData actually converts a here-string to a hash table.

The first command creates a double-quoted here-string that includes one key/value" pair and saves it in the $p variable.

The second command uses a pipeline operator (|) to send the $p variable to the Get-Member cmdlet. The result shows that $p is a string (System.String).

The third command uses the ConvertFrom-StringData cmdlet to convert the here-string in $p to a hash table. The command stores the result in the $hash variable.

The final command uses a pipeline operator (|) to send the $hash variable to the Get-Member cmdlet. The result shows that the content of the $hash variable is a hash table (System.Collections.Hashtable).

PS C:\> $p = @"ISE = Windows PowerShell Integrated Scripting Environment"@PS C:\>$p | get-memberTypeName: System.StringName             MemberType            Definition----             ----------            ----------Clone            Method                System.Object Clone()...PS C:\>$hash = convertfrom-stringdata -stringdata $pPS C:\>$hash | get-memberTypeName: System.Collections.HashtableName              MemberType            Definition----              ----------            ----------Add               Method                System.Void Add(Object key, Object...

This command converts a single-quoted here-string that contains multiple key/value pairs into a hash table.

In this command, the value of the StringData parameter is a here-string, instead of a variable that contains a here-string. Either format is valid.

The here-string includes a comment about one of the strings. Comments are valid in strings, provided that the comment is on a different line than a key/value pair.

PS C:\> convertfrom-stringdata -stringdata @'Name = Disks.ps1# Category is optional.Category = StorageCost = Free'@Name                           Value----                           -----Cost                           FreeCategory                       StorageName                           Disks.ps1

This example converts a regular double-quoted string (not a here-string) into a hash table and saves it in the $a variable.

To satisfy the condition that each key/value pair must be on a separate line, it uses the Windows PowerShell newline character (`n) to separate the pairs.

The result is a hash table of the input. The remaining commands display the output.

PS C:\> $a = convertfrom-stringdata -stringdata "Top = Red `n Bottom = Blue"PS C:\>"Top = " + $a.TopTop = RedPS C:\>"Bottom = " + $a.BottomBottom = Blue

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.

Because the text includes variable names, it must be enclosed in a single-quoted string so that the variables are interpreted literally and not expanded. Variables are not permitted in the DATA section.

PS C:\> $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.'@}PS C:\>$TextMsgs.Text001The $Notebook variable contains the name of the user's system notebook.PS C:\>$TextMsgs.Text002The $MyNotebook variable contains the name of the user's private notebook.

This example shows that you can use a pipeline operator (|) to send a string to ConvertFrom-StringData.

The first command saves a here-string in the $here variable. The second command uses a pipeline operator (|) to send the $here variable to ConvertFrom-StringData. The command saves the result in the $hash variable.

The final command displays the contents of the $hash variable.

PS C:\> $here = @'Msg1 = The string parameter is required.Msg2 = Credentials are required for this command.Msg3 = The specified variable does not exist.'@PS C:\>$hash = $here | convertfrom-stringdataPS C:\>$hashName     Value----     -----Msg3     The specified variable does not exist.Msg2     Credentials are required for this command.Msg1     The string parameter is required.