Category Archives: ConvertFrom

ConvertFrom-Csv

February 26, 2014 Adam

SYNOPSIS
Converts object properties in comma-separated value (CSV) format into CSV versions of the original objects.

SYNTAX
ConvertFrom-Csv [[-Delimiter] <char>] [-InputObject] <PSObject[]> [-Header <string[]>] [<CommonParameters>]

ConvertFrom-Csv -UseCulture [-InputObject] <PSObject[]> [-Header <string[]>] [<CommonParameters>]

DESCRIPTION
The ConvertFrom-Csv cmdlet creates objects from CSV Variable-length strings that are generated by the ConvertTo-Csv cmdlet.

You can use the parameters of the ConvertFrom-Csv cmdlet to specify the column header row, which determines the property names of the resulting objects, to specify the item delimiter, or to direct ConvertFrom-Csv to use the list separator for the current culture as the delimiter.

The objects that ConvertFrom-Csv creates are CSV versions of the original objects. The property values of the CSV objects are string versions of the property values of the original objects. The CSV versions of the objects do not have any methods.

You can also use the Export-Csv and Import-Csv cmdlets to convert objects to CSV strings in a file (and back). These cmdlets are the same as the ConvertTo-Csv and ConvertFrom-Csv cmdlets, except that they save the CSV strings in a file.

PARAMETERS
-Delimiter <char>
Specifies the delimiter that separates the property values in the CSV strings. The default is a comma (,). Enter a character, such as a colon (:). To specify a semicolon (;), enclose it in quotation marks.

If you specify a character other than the delimiter used in the CSV strings, ConvertFrom-Csv cannot create objects from the CSV strings. Instead, it returns the strings.

        Required?                    false
        Position?                    2
        Default value                ‘,’
        Accept pipeline input?     false
        Accept wildcard characters? false

-Header <string[]>
Specifies an alternate column header row for the imported string. The column header determines the names of the properties of the object that ConvertFrom-Csv creates.

Enter a comma-separated list of the column headers. Enclose each item in quotation marks (single or double). Do not enclose the header string in quotation marks. If you enter fewer column headers than there are columns, the remaining columns will have no headers. If you enter more headers than there are columns, the extra headers are ignored.

When using the Header parameter, omit the column header string from the CSV strings. Otherwise, ConvertFrom-Csv creates an extra object from the items in the header row.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

-InputObject <PSObject[]>
Specifies the CSV strings to be converted to objects. Enter a Variable that contains the CSV strings or type a command or expression that gets the CSV strings. You can also pipe the CSV strings to ConvertFrom-Csv.

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

-UseCulture [<SwitchParameter>]
Use the list separator for the current culture as the string delimiter. The default is a comma (,).

To find the list separator for a culture, use the following command: (Get-Culture).TextInfo.ListSeparator. If you specify a character other than the delimiter used in the CSV strings, ConvertFrom-Csv cannot create objects from the CSV strings. Instead, it returns the strings.

        Required?                    true
        Position?                    named
        Default value                Comma
        Accept pipeline input?     false
        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 CSV strings to ConvertFrom-Csv.

OUTPUTS
System.Management.Automation.PSObject
ConvertFrom-Csv returns the objects described by the properties in the CSV strings.

NOTES

Because the imported objects are CSV versions of the object type, they are not recognized and formatted by the Windows PowerShell type formatting entries that format the non-CSV versions of the object type.

In CSV format, each object is represented by a comma-separated list of the property values of the object. The property values are converted to strings (by using the ToString() method of the object), so they are generally represented by the name of the property value. ConvertTo-Csv does not export the methods of the object.

————————– EXAMPLE 1 ————————–

C:\PS>$p = Get-Process | ConvertTo-Csv

C:\PS> $p | ConvertFrom-Csv

    Description
    ———–
    These commands convert the processes on the local computer into CSV format and then restore them to object form.

The first command uses the Get-Process cmdlet to get the processes on the local computer. A pipeline operator (|) sends them to the ConvertTo-Csv cmdlet, which converts the process object to CSV format. The CSV strings are saved in the $p Variable.

The second command uses a pipeline operator to send the CSV strings in the $p Variable to the ConvertFrom-Csv cmdlet. The cmdlet converts the CSV strings into CSV versions of the original process objects.

————————– EXAMPLE 2 ————————–

C:\PS>$date = Get-Date | ConvertTo-Csv -Delimiter “;”

C:\PS> ConvertFrom-Csv -InputObject $date -Delimiter “;”

    Description
    ———–
    These commands convert a data object to CSV format and then to CSV object format.

The first command uses the Get-Date cmdlet to get the current date and time. A pipeline object (|) sends the date to the ConvertTo-Csv cmdlets, which converts the date object to a series of CSV strings. The command uses the Delimiter parameter to specify a semicolon delimiter. The strings are saved in the $date Variable.

The second command uses the ConvertFrom-Csv cmdlet to convert the CSV strings in the $date Variable back to object format. The command uses the InputObject parameter to specify the CSV strings and the Delimiter parameter to specify the semicolon delimiter.

————————– EXAMPLE 3 ————————–

C:\PS>$j = Start-Job -scriptblock { Get-Process } | ConvertTo-Csv

C:\PS> $header = “MoreData”,”StatusMessage”,”Location”,”Command”,”State”,”Finished”,”InstanceId”,”SessionId”,”Name”,”ChildJobs”,”Output”,”Error”,”Progress”,”Verbose”,”Debug”,”Warning”,”StateChanged”

# Delete header from $j
C:\PS> $j = $j[0], $j[2..($j.count – 1)]

$j | ConvertFrom-Csv -Header $header

    MoreData     : True
    StatusMessage :
    Location     : localhost
    Command     : Get-Process
    State         : Running
    Finished     : System.Threading.ManualResetEvent
    InstanceId    : 6fcb6578-7f42-4d93-9f23-9937f6aac1a2
    SessionId     : 1
    Name         : Job1
    ChildJobs     : System.Collections.Generic.List`1[System.Management.Automation.Job]
    Output        : System.Management.Automation.PSDataCollection`1[System.Management.Automation.PSObject]
    Error         : System.Management.Automation.PSDataCollection`1[System.Management.Automation.ErrorRecord]
    Progress     : System.Management.Automation.PSDataCollection`1[System.Management.Automation.ProgressRecord]
    Verbose     : System.Management.Automation.PSDataCollection`1[System.String]
    Debug         : System.Management.Automation.PSDataCollection`1[System.String]
    Warning     : System.Management.Automation.PSDataCollection`1[System.String]
    StateChanged :

    Description
    ———–
    This example shows how to use the Header parameter of ConvertFrom-Csv to change the names of properties in the resulting imported object.

The first command uses the Start-Job cmdlet to start a background job that runs a Get-Process command on the local computer. A pipeline operator (|) sends the resulting job object to the ConvertTo-Csv cmdlet, which converts the job object to CSV format. An assignment operator (=) saves the resulting CSV in the $j Variable.

The second command saves a header in the $header Variable. Unlike the default header, this header uses “MoreData” instead of “HasMoreData” and “State” instead of “JobStateInfo”.

The third command deletes the original header (the second line) from the CSV strings and returns it to the $j Variable.

The fourth command uses the ConvertFrom-Csv cmdlet to convert the CSV strings to a CSV version of the job object. The command uses a pipeline operator to send the content in $j to ConvertFrom-Csv. The resulting object has “MoreData” and “State” properties, as specified by the header.

————————– EXAMPLE 4 ————————–

C:\PS>(Get-Culture).textinfo.listseparator

C:\PS> ConvertFrom-Csv -InputObject $services -UseCulture

    Description
    ———–
    The command uses the ConvertFrom-Csv cmdlet to convert CSV strings of service objects that had been converted by the ConvertTo-Csv cmdlet. The command uses the UseCulture parameter to direct ConvertFrom-Csv to use the delimiter (list separator) of the current culture.

When using the UseCulture parameter, be sure that the list separator of the current culture matches the delimiter used in the CSV strings. Otherwise, ConvertFrom-Csv cannot generate objects from the CSV strings.

In this example, a Get-Culture command was used to verify the list separator, before the ConvertFrom-Csv command was used.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=135201
    ConvertTo-Csv
    Export-Csv
    Import-Csv

cmdlet, ConvertFrom, SecureString

ConvertFrom-SecureString

February 26, 2014 Adam

NAME
ConvertFrom-SecureString

SYNOPSIS
Converts a secure string into an encrypted standard string.

SYNTAX
ConvertFrom-SecureString [-Key <Byte[]>] [-SecureString] <SecureString> [<CommonParameters>]

ConvertFrom-SecureString [[-SecureKey] <SecureString>] [-SecureString] <SecureString> [<CommonParameters>]

DESCRIPTION
The ConvertFrom-SecureString cmdlet converts a secure string (System.Security.SecureString) into an encrypted standard string (System.String). Unlike a secure string, an encrypted standard string can be saved in a file for later use. The encrypted standard string can be converted back to its secure string format by using the ConvertTo-SecureString cmdlet. If an encryption key is specified by using the Key or SecureKey parameters, the Rijndael encryption algorithm is used. The specified key must have a length of 128, 192, or 256 bits because those are the key lengths supported by the Rijndael encryption algorithm. If no key is specified, the Windows Data Protection API (DPAPI) is used to encrypt the standard string representation.

PARAMETERS
-Key <Byte[]>
Specifies the encryption key as a byte array.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

-SecureKey <SecureString>
Specifies the encryption key as a secure string. The secure string value is converted to a byte array before being used as the key.

        Required?                    false
        Position?                    2
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

-SecureString <SecureString>
Specifies the secure string to convert to an encrypted standard string.

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

INPUTS
System.Security.SecureString
You can pipe a SecureString object to ConvertFrom-SecureString.

OUTPUTS
System.String
ConvertFrom-SecureString returns a standard string object.

NOTES

To create a secure string from characters that are typed at the command prompt, use the AsSecureString parameter of the Read-Host cmdlet.

When you use the Key or SecureKey parameters to specify a key, the key length must be correct. For example, a key of 128 bits can be specified as a byte array of 16 digits. Similarly, 192-bit and 256-bit keys correspond to byte arrays of 24 and 32 digits, respectively.

————————– EXAMPLE 1 ————————–

C:\PS>$securestring = Read-Host -assecurestring

    Description
    ———–
    This command creates a secure string from characters that you type at the command prompt. After entering the command, type the string you want to store as a secure string. An asterisk (*) will be displayed to represent each character that you type.

————————– EXAMPLE 2 ————————–

C:\PS>$standardstring = ConvertFrom-SecureString $securestring

    Description
    ———–
    This command converts the secure string in the $securestring Variable to an encrypted standard string. The resulting encrypted standard string is stored in the $standardstring Variable.

————————– EXAMPLE 3 ————————–

C:\PS>$key = (3,4,2,3,56,34,254,222,1,1,2,23,42,54,33,233,1,34,2,7,6,5,35,43)

C:\PS> $standardstring = ConvertFrom-SecureString $securestring -key $key

    Description
    ———–
    These commands use the Rijndael algorithm to convert the secure string stored in the $securestring Variable to an encrypted standard string with a 192-bit key. The resulting encrypted standard string is stored in the $standardstring Variable.

The first command stores a key in the $key Variable. The key is an array of 24 digits, all of which are less than 256.

Because each digit represents a byte (8 bits), the key has 24 digits for a total of 192 bits (8 x 24). This is a valid key length for the Rijndael algorithm. Each individual value is less than 256, which is the maximum value that can be stored in an unsigned byte.

The second command uses the key in the $key Variable to convert the secure string to an encrypted standard string.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=113287
    ConvertTo-SecureString
    Read-Host

cmdlet, ConvertFrom, StringData

ConvertFrom-StringData

February 26, 2014 Adam

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

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