powershellscripts.com

Tutorials  PowerShell Cmdlet Help for ConvertFrom-StringData



NAME
ConvertFrom-StringData

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

SYNTAX
ConvertFrom-StringData [-StringData] []


DESCRIPTION
The ConvertFrom-StringData cmdlet converts a string that contains one or more key/value pairs into a hash table. B
ecause 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 scrip
t 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
Specifies the string to be converted. You can use this parameter or pipe a string to ConvertFrom-StringData. Th
e 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 o
ne or more key/value pairs. Each key/value pair must be on a separate line, or each pair must be separated by n
ewline characters (`n).

You can include comments in the string, but the comments cannot be on the same line as a key/value pair. The co
mments 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 literall
y. For more information, see about_Quoting_Rules.

Required? true
Position? 1
Default value
Accept pipeline input? true (ByValue)
Accept wildcard characters? false


This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
OutBuffer and OutVariable. For more information, type,
"get-help about_commonparameters".

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


OUTPUTS
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 literall
y. For more information, see about_Quoting_Rules.

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


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

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

C:\PS> 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.


Description
-----------
These commands convert a single-quoted here-string of user messages into a hash table. In a single-quoted string, v
alues 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 has
h table.





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

C:\PS>$p = @"
ISE = Windows PowerShell Integrated Scripting Environment
"@

C:\PS> $p | get-member

TypeName: System.String

Name MemberType Definition
---- ---------- ----------
Clone Method System.Object Clone()
...


C:\PS> $hash = convertfrom-stringdata -stringdata $p

C:\PS> $hash | get-member

TypeName: System.Collections.Hashtable

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


Description
-----------
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 vari
able.

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 comm
and 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 show
s that the content of the $hash variable is a hash table (System.Collections.Hashtable).





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

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

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


Description
-----------
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 comme
nt is on a different line than a key/value pair.





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

C:\PS>$a = convertfrom-stringdata -stringdata "Top = Red `n Bottom = Blue"

C:\PS> "Top = " + $a.Top
Top = Red

C:\PS> "Bottom = " + $a.Bottom
Bottom = Blue


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

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

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





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

C:\PS>$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.
'@
}

C:\PS> $TextMsgs.Text001
The $Notebook variable contains the name of the user's system notebook.


C:\PS> $TextMsgs.Text002
The $MyNotebook variable contains the name of the user's private notebook.


Description
-----------
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 i
nterpreted literally and not expanded. Variables are not permitted in the DATA section.





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

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

C:\PS> $hash = $here | convertfrom-stringdata

C:\PS> $hash

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


Description
-----------
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 sen
d 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.






RELATED LINKS
Online version: http://go.microsoft.com/fwlink/?LinkID=113288
about_Data_Sections
about_Quoting_Rules
about_Script_Internationalization