This is the built-in help made by Microsoft for the command 'ConvertFrom-StringData', in PowerShell version 3 - as retrieved from
Windows version 'Microsoft Windows Server 2012 Standard' PowerShell help files on 2016-06-23.
For PowerShell version 3 and up, where you have Update-Help, this command was run just before creating the web pages from the help files.
Converts a string containing one or more key/value pairs to a hash table.
ConvertFrom-StringData [-StringData] <String> [<CommonParameters>]
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.
<
Online Version: http://go.microsoft.com/fwlink/?LinkID=113288
about_Quoting_Rules
about_Script_Internationalization
about_Data_Sections
<
-------------------------- EXAMPLE 1 --------------------------
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.
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.
-------------------------- EXAMPLE 2 --------------------------
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
...
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).
-------------------------- EXAMPLE 3 --------------------------
PS C:\>convertfrom-stringdata -stringdata @'
Name = Disks.ps1
# Category is optional.
Category = Storage
Cost = Free
'@
Name Value
---- -----
Cost Free
Category Storage
Name Disks.ps1
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.
-------------------------- EXAMPLE 4 --------------------------
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
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.
-------------------------- EXAMPLE 5 --------------------------
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.
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.
-------------------------- EXAMPLE 6 --------------------------
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.
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.