ConvertFrom-StringData

NAME
    ConvertFrom-StringData

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

SYNTAX
    ConvertFrom-StringData [-StringData] <string> [<CommonParameters>]

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.

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

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

    ————————– 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, 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 ————————–

    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 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 ————————–

    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 comment 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 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 ————————–

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

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