Export (0) Print
Expand All

ConvertFrom-StringData

Published: February 29, 2012

Updated: August 15, 2012

Applies To: Windows PowerShell 2.0, Windows PowerShell 3.0

ConvertFrom-StringData

Converts a string containing one or more key/value pairs to a hash table.

Syntax

Parameter Set: Default
ConvertFrom-StringData [-StringData] <String> [ <CommonParameters>]




Detailed Description

The ConvertFrom-StringData cmdlet converts a string that contains one or more key/value pairs into a hash table. Because each key/value pair must be on a separate line, here-strings are often used as the input format.

The ConvertFrom-StringData cmdlet is considered to be a safe cmdlet that can be used in the DATA section of a script or function. When used in a DATA section, the contents of the string must conform to the rules for a DATA section. For more information, see about_Data_Sections.

Parameters

-StringData<String>

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.


Aliases

none

Required?

true

Position?

1

Default Value

none

Accept Pipeline Input?

true (ByValue)

Accept Wildcard Characters?

false

<CommonParameters>

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).

Inputs

The input type is the type of the objects that you can pipe to the cmdlet.

  • System.String

    You can pipe a string containing a key/value pair to ConvertFrom-StringData.


Outputs

The output type is the type of the objects that the cmdlet emits.

  • System.Collections.Hashtable

    ConvertFrom-StringData 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 are interpreted literally. For more information, see about_Quoting_Rules.

    ConvertFrom-StringData can be useful in scripts that display user messages in multiple spoken languages. You can use the dictionary-style hash tables to isolate text strings from code, such as in resource files, and to format the text strings for use in translation tools.

Examples

-------------------------- EXAMPLE 1 --------------------------

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 $here

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

-------------------------- EXAMPLE 2 --------------------------

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-member
TypeName: System.String

Name             MemberType            Definition
----             ----------            ----------
Clone            Method                System.Object Clone()
...
PS C:\>$hash = convertfrom-stringdata -stringdata $p
PS C:\>$hash | get-member
TypeName: System.Collections.Hashtable

Name              MemberType            Definition
----              ----------            ----------
Add               Method                System.Void Add(Object key, Object
...

-------------------------- EXAMPLE 3 --------------------------

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 = Storage
Cost = Free
'@

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

-------------------------- EXAMPLE 4 --------------------------

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.Top
Top = Red
PS C:\>"Bottom = " + $a.Bottom
Bottom = Blue

-------------------------- EXAMPLE 5 --------------------------

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

-------------------------- EXAMPLE 6 --------------------------

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-stringdata
PS C:\>$hash

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

Related topics



Was this page helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft