Tag Archives: ErrorVariable

Disable-ComputerRestore

February 26, 2014 Adam

SYNOPSIS
Disables the System Restore feature on the specified file system drive.

SYNTAX
Disable-ComputerRestore [-Drive] <string[]> [-Confirm] [-WhatIf] [<CommonParameters>]

DESCRIPTION
The Disable-ComputerRestore cmdlet turns off the System Restore feature on one or more file system drives. As a result, attempts to restore the computer do not affect the specified drive.

To disable System Restore on any drive, it must be disabled on the system drive, either first or concurrently.

To re-enable System Restore, use the Enable-ComputerRestore cmdlet. To find the state of System Restore for each drive, use Rstrui.exe.

PARAMETERS
-Drive <string[]>
Specifies the file system drives. Enter one or more file system drive letters, each followed by a colon and a backslash and enclosed in quotation marks, such as “C:\” or “D:\”. This parameter is required.

You cannot use this cmdlet to disable System Restore on a remote network drive, even if the drive is mapped to the local computer, and you cannot disable System Restore on drives that are not eligible for System Restore, such as external drives.

To disable System Restore on any drive, System Restore must be disabled on the system drive, either before or concurrently.

        Required?                    true
        Position?                    1
        Default value                None
        Accept pipeline input?     false
        Accept wildcard characters? false

-Confirm [<SwitchParameter>]
Prompts you for confirmation before executing the command.

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

-WhatIf [<SwitchParameter>]
Describes what would happen if you executed the command without actually executing the command.

        Required?                    false
        Position?                    named
        Default value
        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
None
You cannot pipe input to this cmdlet.

OUTPUTS
None
This cmdlet does not generate any output.

NOTES

Disable-ComputerRestore and Enable-ComputerRestore work only on client operating systems, such as Windows Vista and Windows XP.

To run a Disable-ComputerRestore command on Windows Vista and later versions of Windows, open Windows PowerShell with the “Run as administrator” option.

To find the file system drives that are eligible for system restore, in System in Control Panel, see the System Protection tab. To open this tab in Windows PowerShell, type “SystemPropertiesProtection”.

This cmdlet uses the Windows Management Instrumentation (WMI) SystemRestore class.

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

C:\PS>Disable-ComputerRestore -Drive “C:\”

    Description
    ———–
    This command disables System Restore on the C: drive.

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

C:\PS>Disable-ComputerRestore “C:\”, “D:\”

    Description
    ———–
    This command disables System Restore on the C: and D: drives. The command uses the Drive parameter, but it the omits the optional parameter name.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=135207
    Enable-ComputerRestore
    Get-ComputerRestorePoint
    Restore-Computer
    Restart-Computer

cmdlet, ConvertTo, Xml

ConvertTo-Xml

February 26, 2014 Adam

NAME
ConvertTo-Xml

SYNOPSIS
Creates an XML-based representation of an object.

SYNTAX
ConvertTo-Xml [-InputObject] <psobject> [-As <string>] [-Depth <int>] [-NoTypeInformation] [<CommonParameters>]

DESCRIPTION
The ConvertTo-Xml cmdlet creates an XML-based representation of one or more Microsoft .NET Framework objects. To use this cmdlet, pipe one or more objects to the cmdlet, or use the InputObject parameter to specify the object.

When you pipe multiple objects to ConvertTo-Xml or use the InputObject parameter to submit multiple objects, ConvertTo-Xml returns a single XML document that includes representations of all of the objects.

This cmdlet is similar to Export-Clixml except that Export-Clixml stores the resulting XML in a file. ConvertTo-Xml returns the XML, so you can continue to process it in Windows PowerShell.

PARAMETERS
-As <string>
Determines the output format. Valid values are:

        — String: Returns a single string.
        — Stream: Returns an array of strings.
        — Document: Returns an XmlDocument object.

Stream is the default.

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

-Depth <int>
Specifies how many levels of contained objects are included in the XML representation. The default value is 1.

For example, if the object’s properties also contain objects, to save an XML representation of the properties of the contained objects, you must specify a depth of 2.

The default value can be overridden for the object type in the Types.ps1xml files. For more information, see about_types.ps1xml.

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

-InputObject <psobject>
Specifies the object to be converted. Enter a Variable that contains the objects, or type a command or expression that gets the objects. You can also pipe objects to ConvertTo-Xml.

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

-NoTypeInformation [<SwitchParameter>]
Omits the Type attribute from the object nodes.

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

INPUTS
System.Management.Automation.PSObject
You can pipe any object to ConvertTo-Xml.

OUTPUTS
System.String or System.Xml.XmlDocument
The value of the As parameter determines the type of object that ConvertTo-Xml returns.

NOTES

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

C:\PS>Get-Date | ConvertTo-Xml

    Description
    ———–
    This command converts the current date (a DateTime object) to XML.

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

C:\PS>ConvertTo-Xml -As Document -InputObject (Get-Process) -Depth 3

    Description
    ———–
    This command converts the process objects that represent all of the processes on the computer into an XML document. The objects are expanded to a depth of three levels.

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

cmdlet, Copy, Item

Copy-Item

February 26, 2014 Adam

NAME
Copy-Item

SYNOPSIS
Copies an item from one location to another within a namespace.

SYNTAX
Copy-Item [-LiteralPath] <string[]> [[-Destination] <string>] [-Container] [-Credential <PSCredential>] [-Exclude <string[]>] [-Filter <string>] [-Force] [-Include <string[]>] [-PassThru] [-Recurse] [-Confirm] [-WhatIf] [-UseTransaction] [<CommonParameters>]

Copy-Item [-Path] <string[]> [[-Destination] <string>] [-Container] [-Credential <PSCredential>] [-Exclude <string[]>] [-Filter <string>] [-Force] [-Include <string[]>] [-PassThru] [-Recurse] [-Confirm] [-WhatIf] [-UseTransaction] [<CommonParameters>]

DESCRIPTION
The Copy-Item cmdlet copies an item from one location to another in a namespace. Copy-Item does not delete the items being copied. The particular items that the cmdlet can copy depend on the Windows PowerShell providers available. For example, when used with the FileSystem provider, it can copy files and directories and when used with the Registry provider, it can copy Registry keys and entries.

PARAMETERS
-Container [<SwitchParameter>]
Preserves container objects during the copy operation.

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

-Credential <PSCredential>
Specifies a user account that has permission to perform this action. The default is the current user.

Type a user name, such as “User01” or “Domain01\User01”, or enter a PSCredential object, such as one generated by the Get-Credential cmdlet. If you type a user name, you will be prompted for a password.

This parameter is not supported by any providers installed with Windows PowerShell.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     true (ByPropertyName)
        Accept wildcard characters? false

-Destination <string>
Specifies the path to the location where the items are to be copied.

        Required?                    false
        Position?                    2
        Default value
        Accept pipeline input?     true (ByPropertyName)
        Accept wildcard characters? false

-Exclude <string[]>
Omits the specified items. Wildcards are permitted.

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

-Filter <string>
Specifies a filter in the provider’s format or language. The value of this parameter qualifies the Path parameter. The syntax of the filter, including the use of wildcards, depends on the provider. Filters are more efficient than other parameters, because the provider applies them when retrieving the objects, rather than having Windows PowerShell filter the objects after they are retrieved.

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

-Force [<SwitchParameter>]
Allows the cmdlet to copy items that cannot otherwise be changed, such as copying over a read-only file or Alias.

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

-Include <string[]>
Specifies only those items upon which the cmdlet will act, excluding all others.

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

-LiteralPath <string[]>
Specifies a path to the item. The value of the LiteralPath parameter is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences.

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

-PassThru [<SwitchParameter>]
Returns an object representing each copied item. By default, this cmdlet does not generate any output.

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

-Path <string[]>
Specifies the path to the items to copy.

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

-Recurse [<SwitchParameter>]
Specifies a recursive copy.

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

-Confirm [<SwitchParameter>]
Prompts you for confirmation before executing the command.

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

-WhatIf [<SwitchParameter>]
Describes what would happen if you executed the command without actually executing the command.

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

-UseTransaction [<SwitchParameter>]
Includes the command in the active transaction. This parameter is valid only when a transaction is in progress. For more information, see about_transactions.

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

INPUTS
System.String
You can pipe a string that contains a path to Copy-ItemProperty.

OUTPUTS
None or an object representing the copied item.
When you use the PassThru parameter, Copy-Item returns an object that represents the copied item. Otherwise, this cmdlet does not generate any output.

NOTES

Copy-Item is like the ‘cp’ or ‘copy’ commands in other shells.

The Copy-Item cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, type “Get-PSProvider“. For more information, see about_providers.

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

C:\PS>Copy-Item C:\Wabash\Logfiles\mar1604.log.txt -Destination C:\Presentation

    Description
    ———–
    This command will copy the file mar1604.log.txt to the C:\Presentation directory. The command does not delete the original file.

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

C:\PS>Copy-Item C:\Logfiles -Destination C:\Drawings -Recurse

    Description
    ———–
    This command copies the entire contents of the Logfiles directory into the Drawings directory. If the source directory contains files in subdirectories, those subdirectories will be copied with their file trees intact. The Container parameter is set to true by default. This preserves the directory structure.

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

C:\PS>Copy-Item C:\Logfiles -Destination C:\Drawings\Logs -Recurse

    Description
    ———–
    This command copies the contents of the C:\Logfiles directory to the C:\Drawings\Logs directory. It will create the subdirectory \Logs if it does not already exist.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=113292
    about_providers
    Clear-Item
    Get-Item
    Invoke-Item
    Move-Item
    Set-Item
    New-Item
    Remove-Item
    Rename-Item

cmdlet, ConvertTo, Html

ConvertTo-Html

February 26, 2014 Adam

NAME
ConvertTo-Html

SYNOPSIS
Converts Microsoft .NET Framework objects into HTML that can be displayed in a Web browser.

SYNTAX
ConvertTo-Html [[-Head] <string[]>] [[-Title] <string>] [[-Body] <string[]>] [-CssUri <Uri>] [[-Property] <Object[]>] [-As <string>] [-InputObject <psobject>] [-PostContent <string[]>] [-PreContent <string[]>] [<CommonParameters>]

ConvertTo-Html [-Fragment] [[-Property] <Object[]>] [-As <string>] [-InputObject <psobject>] [-PostContent <string[]>] [-PreContent <string[]>] [<CommonParameters>]

DESCRIPTION
The ConvertTo-Html cmdlet converts .NET Framework objects into HTML that can be displayed in a Web browser. You can use this cmdlet to display the output of a command in a Web page.

You can use the parameters of ConvertTo-Html to select object properties, to specify a table or list format, to specify the HTML page title, to add text before and after the object, and to return only the table or list fragment, instead of a strict DTD page.

When you submit multiple objects to ConvertTo-Html, Windows PowerShell creates the table (or list) based on the properties of the first object that you submit. If the remaining objects do not have one of the specified properties, the property value of that object is an empty cell. If the remaining objects have additional properties, those property values are not included in the file.

PARAMETERS
-As <string>
Determines whether the object is formatted as a table or a list. Valid values are TABLE and LIST. The default value is TABLE.

The TABLE value generates an HTML table that resembles the Windows PowerShell table format. The header row displays the property names. Each table row represents an object and displays the object’s values for each property.

The LIST value generates a two-column HTML table for each object that resembles the Windows PowerShell list format. The first column displays the property name; the second column displays the property value.

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

-Body <string[]>
Specifies the text to add after the opening <BODY> tag. By default, there is no text in that position.

        Required?                    false
        Position?                    4
        Default value                No text.
        Accept pipeline input?     false
        Accept wildcard characters? false

-CssUri <Uri>
Specifies the Uniform Resource Identifier (URI) of the cascading style sheet (CSS) that is applied to the HTML file. The URI is included in a style sheet link in the output.

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

-Fragment [<SwitchParameter>]
Generates only an HTML table. The HTML, HEAD, TITLE, and BODY tags are omitted.

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

-Head <string[]>
Specifies the content of the <HEAD> tag. The default is “<title>HTML TABLE</title>”. If you use the Head parameter, the Title parameter is ignored.

        Required?                    false
        Position?                    2
        Default value                <title>HTML TABLE</title>
        Accept pipeline input?     false
        Accept wildcard characters? false

-InputObject <psobject>
Specifies the objects to be represented in HTML. Enter a Variable that contains the objects or type a command or expression that gets the objects.

If you use this parameter to submit multiple objects, such as all of the services on a computer, ConvertTo-Html creates a table that displays the properties of a collection or of an array of objects (System.Object[]). To create a table of the individual objects, use the pipeline operator to pipe the objects to ConvertTo-Html.

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

-PostContent <string[]>
Specifies text to add after the closing </TABLE> tag. By default, there is no text in that position.

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

-PreContent <string[]>
Specifies text to add before the opening <TABLE> tag. By default, there is no text in that position.

-Property <Object[]>
Includes the specified properties of the objects in the HTML.

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

-Title <string>
Specifies a title for the HTML file, that is, the text that appears between the <TITLE> tags.

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

INPUTS
System.Management.Automation.PSObject
You can pipe any .NET object to ConvertTo-Html.

OUTPUTS
System.String
ConvertTo-Html returns series of strings that comprise valid HTML.

NOTES

To use this cmdlet, pipe one or more objects to the cmdlet or use the InputObject parameter to specify the object. When the input consists of multiple objects, the output of these two methods is quite different.

— When you pipe multiple objects to a cmdlet, Windows PowerShell sends the objects to the cmdlet one at a time. As a result, ConvertTo-Html creates a table that displays the individual objects. For example, if you pipe the processes on a computer to ConvertTo-Html, the resulting table displays all of the processes.

— When you use the InputObject parameter to submit multiple objects, ConvertTo-Html receives these objects as a collection or as an array. As a result, it creates a table that displays the array and its properties, not the items in the array. For example, if you use InputObject to submit the processes on a computer to ConvertTo-Html, the resulting table displays an object array (System.Object[]) and its properties.

To comply with the XHTML Strict DTD,the DOCTYPE tag is modified accordingly:
(<!DOCTYPE html PUBLIC “-//W3C//DTD XHTML 1.0 Strict//EN” “http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd”>)

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

C:\PS>ConvertTo-Html -InputObject (Get-Date)

    Description
    ———–
    This command creates an HTML page that displays the properties of the current date. It uses the InputObject parameter to submit the results of a Get-Date command to the ConvertTo-Html cmdlet.

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

C:\PS>Get-Alias | ConvertTo-Html > Aliases.htm

C:\PS> Invoke-Item Aliases.htm

    Description
    ———–
    This command creates an HTML page that lists the Windows PowerShell Aliases in the current console.

The command uses the Get-Alias cmdlet to get the Aliases. It uses the pipeline operator (|) to send the Aliases to the ConvertTo-Html cmdlet, which creates the HTML page.

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

C:\PS>Get-Eventlog -logname “Windows PowerShell | ConvertTo-Html > pslog.htm

    Description
    ———–
    This command creates an HTML page called pslog.htm that displays the events in the Windows PowerShell event log on the local computer.

It uses the Get-EventLog cmdlet to get the events in the Windows PowerShell log and then uses the pipeline operator (|) to send the events to the ConvertTo-Html cmdlet.

The command also uses the redirection operator (>) to send the HTML code to the pslog.htm file.

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

C:\PS>Get-Process | ConvertTo-Html -Property Name, Path, Company -Title “Process Information” > proc.htm; ii proc.htm

    Description
    ———–
    These commands create and open an HTML page that lists the name, path, and company of the processes on the local computer.

The first command uses the Get-Process cmdlet to get objects that represent the processes running on the computer. The command uses the pipeline operator (|) to send the process objects to the ConvertTo-Html cmdlet.

The command uses the Property parameter to select three properties of the process objects to be included in the table. The command uses the Title parameter to specify a title for the HTML page. The command also uses the redirection operator (>) to send the resulting HTML to a file named Proc.htm.

The second command uses the Invoke-Item cmdlet (alias = ii) to open the Proc.htm in the default browser. The two commands are separated by a semicolon (;).

————————– EXAMPLE 5 ————————–

C:\PS>Get-Service | ConvertTo-Html -CssUri “test.css”

    <!DOCTYPE html PUBLIC “-//W3C//DTD XHTML 1.0 Strict//EN”     “http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd”>
    <html>
    <head>
    <title>HTML TABLE</title>
    <link rel=”stylesheet” type=”text/css” href=”test.css” />
    …

    Description
    ———–
    This command creates an HTML page of the service objects that the Get-Service cmdlet returns. The command uses the CssUri parameter to specify a cascading style sheet for the HTML page.

The CssUri parameter adds an additional “<link rel=”stylesheet” type=”text/css” tag to the resulting HTML. The HREF attribute in the tag contains the name of the style sheet.

————————– EXAMPLE 6 ————————–

C:\PS>Get-Service | ConvertTo-Html -As LIST > services.htm

    Description
    ———–
    This command creates an HTML page of the service objects that the Get-Service cmdlet returns. The command uses the As parameter to specify a list format. The redirection operator (>) sends the resulting HTML to the Services.htm file.

————————– EXAMPLE 7 ————————–

C:\PS>Get-Date | cth -fragment

    <table>
    <colgroup>…</colgroup>
    <tr><th>DisplayHint</th><th>DateTime</th><th>Date</th><th>Day</th><th>DayOfWeek</th><th>DayOfYear</th><th>Hour</th><th>
    Kind</th><th>Millisecond</th><th>Minute</th><th>Month</th><th>Second</th><th>Ticks</th><th>TimeOfDay</th><th>Year</th><
    /tr>
    <tr><td>DateTime</td><td>Monday, May 05, 2008 10:40:04 AM</td><td>5/5/2008 12:00:00 AM</td><td>5</td><td>Monday</td><td
    >126</td><td>10</td><td>Local</td><td>123</td><td>40</td><td>5</td><td>4</td><td>633455808041237213</td><td>10:40:04.12
    37213</td><td>2008</td></tr>
    </table>

    Description
    ———–
    This command uses ConvertTo-Html to generate an HTML table of the current date. The command uses the Get-Date cmdlet to get the current date. It uses a pipeline operator (|) to send the results to the ConvertTo-Html cmdlet (aliased as “cth”).

The ConvertTo-Html command includes the Fragment parameter, which limits the output to an HTML table. As a result, the other elements of an HTML page, such as the <HEAD> and <BODY> tags, are omitted.

————————– EXAMPLE 8 ————————–

C:\PS>Get-Eventlog -log “Windows PowerShell” | ConvertTo-Html -Property id, level, task

    Description
    ———–
    This command uses the Get-EventLog cmdlet to get events from the “Windows PowerShell” event log.

It uses a pipeline operator (|) to send the events to the ConvertTo-Html cmdlet, which converts the events to HTML format.

The ConvertTo-Html command uses the Property parameter to select only the ID, Level, and Task properties of the event.

————————– EXAMPLE 9 ————————–

C:\PS>Get-Service A* | ConvertTo-Html -Title “Windows Services: Server01” -Body (Get-Date) -pre “<P>Generated by Corporate IT</P
>” -post “For details, contact Corporate IT.” > services.htm; ii services.htm

    Description
    ———–
    This command creates and opens a Web page that displays the services on the computer that begin with “A”. It uses the Title, Body, PreContent, and PostContent parameters of ConvertTo-Html to customize the output.

The first part of the command uses the Get-Service cmdlet to get the services on the computer that begin with “A”. The command uses a pipeline operator (|) to send the results to the ConvertTo-Html cmdlet. The command uses a redirection operator (>) to send the output to the Services.htm file.

A semicolon (;) ends the first command and starts a second command, which uses the Invoke-Item cmdlet (alias = “ii”) to open the Services.htm file in the default browser.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=113290
    ConvertTo-Csv
    ConvertTo-Xml

cmdlet, ConvertTo, SecureString

ConvertTo-SecureString

February 26, 2014 Adam

NAME
ConvertTo-SecureString

SYNOPSIS
Converts encrypted standard strings to secure strings. It can also convert plain text to secure strings. It is used with ConvertFrom-SecureString and Read-Host.

SYNTAX
ConvertTo-SecureString [-Key <Byte[]>] [-String] <string> [<CommonParameters>]

ConvertTo-SecureString [[-AsPlainText]] [[-Force]] [-String] <string> [<CommonParameters>]

ConvertTo-SecureString [[-SecureKey] <SecureString>] [-String] <string> [<CommonParameters>]

DESCRIPTION
The ConvertTo-SecureString cmdlet converts encrypted standard strings into secure strings. It can also convert plain text to secure strings. It is used with ConvertFrom-SecureString and Read-Host. The secure string created by the cmdlet can be used with cmdlets or Functions that require a parameter of type SecureString. The secure string can be converted back to an encrypted, standard string using the ConvertFrom-SecureString cmdlet. This enables it to be stored in a file for later use.

If the standard string being converted was encrypted with ConvertFrom-SecureString using a specified key, that same key must be provided as the value of the Key or SecureKey parameter of the ConvertTo-SecureString cmdlet.

PARAMETERS
-AsPlainText [<SwitchParameter>]
Specifies a plain text string to convert to a secure string. The secure string cmdlets help protect confidential text. The text is encrypted for privacy and is deleted from computer memory after it is used. If you use this parameter to provide plain text as input, the system cannot protect that input in this manner. To use this parameter, you must also specify the Force parameter.

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

-Force [<SwitchParameter>]
Confirms that you understand the implications of using the AsPlainText parameter and still want to use it.

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

-Key <Byte[]>
Specifies the encryption key to use when converting a secure string into an encrypted standard string. Valid key lengths are 16, 24, and 32 bytes.

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

-SecureKey <SecureString>
Specifies the encryption key to use when converting a secure string into an encrypted standard string. The key must be provided in the format of a secure string. The secure string is converted to a byte array before being used as the key. Valid key lengths are 16, 24, and 32 bytes.

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

-String <string>
Specifies the string to convert to a secure string.

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

INPUTS
System.String
You can pipe a standard encrypted string to ConvertTo-SecureString.

OUTPUTS
System.Security.SecureString
ConvertTo-SecureString returns a SecureString object.

NOTES

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

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

C:\PS> $secure
System.Security.SecureString

    C:\PS> $encrypted = ConvertFrom-SecureString -securestring $secure
    C:\PS> $encrypted
    01000000d08c9ddf0115d1118c7a00c04fc297eb010000001a114d45b8dd3f4aa11ad7c0abdae9800000000002000000000003660000a8000000100000005df63cea84bfb7d70bd6842e7
    efa79820000000004800000a000000010000000f10cd0f4a99a8d5814d94e0687d7430b100000008bf11f1960158405b2779613e9352c6d14000000e6b7bf46a9d485ff211b9b2a2df3bd
    6eb67aae41

    C:\PS> $secure2 = ConvertTo-SecureString -String $encrypted
    C:\PS> $secure2
    System.Security.SecureString

    Description
    ———–
    This example shows how to create a secure string from user input, convert the secure string to an encrypted standard string, and then convert the encrypted standard string back to a secure string.

The first command uses the AsSecureString parameter of the Read-Host cmdlet to create a secure string. After you enter the command, any characters that you type are converted into a secure string and then saved in the $secure Variable.

The second command displays the contents of the $secure Variable. Because the $secure Variable contains a secure string, Windows PowerShell displays only the System.Security.SecureString type.

The third command uses the ConvertFrom-SecureString cmdlet to convert the secure string in the $secure Variable into an encrypted standard string. It saves the result in the $encrypted Variable. The fourth command displays the encrypted string in the value of the $encrypted Variable.

The fifth command uses the ConvertTo-SecureString cmdlet to convert the encrypted standard string in the $encrypted Variable back into a secure string. It saves the result in the $secure2 Variable. The sixth command displays the value of the $secure2 Variable. The SecureString type indicates that the command was successful.

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

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

C:\PS> $encrypted = ConvertFrom-SecureString -secureString $secure -key (1..16)

C:\PS> $encrypted | Set-Content encrypted.txt

C:\PS> $secure2 = Get-Content encrypted.txt | ConvertTo-SecureString -key (1..16)

    Description
    ———–
    This example shows how to create a secure string from an encrypted standard string that is saved in a file.

The second command uses the ConvertFrom-SecureString cmdlet to convert the secure string in the $secure Variable into an encrypted standard string by using the specified key. The contents are saved in the $encrypted Variable.

The third command uses a pipeline operator (|) to send the value of the $encrypted Variable to the Set-Content cmdlet, which saves the value in the Encrypted.txt file.

The fourth command uses the Get-Content cmdlet to get the encrypted standard string in the Encrypted.txt file. The command uses a pipeline operator to send the encrypted string to the ConvertTo-SecureString cmdlet, which converts it to a secure string by using the specified key. The results are saved in the $secure2 Variable.

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

C:\PS>$secure_string_pwd = ConvertTo-SecureString “P@ssW0rD!” -asplaintext -force

    Description
    ———–
    This command converts the plain text string “P@ssW0rD!” into a secure string and stores the result in the $secure_string_pwd Variable. To use the AsPlainText parameter, the Force parameter must also be included in the command.

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

cmdlet, Convert, Path

Convert-Path

February 26, 2014 Adam

NAME
Convert-Path

SYNOPSIS
Converts a path from a Windows PowerShell path to a Windows PowerShell provider path.

SYNTAX
Convert-Path [-LiteralPath] <string[]> [-UseTransaction] [<CommonParameters>]

Convert-Path [-Path] <string[]> [-UseTransaction] [<CommonParameters>]

DESCRIPTION
The Convert-Path cmdlet converts a path from a Windows PowerShell path to a Windows PowerShell provider path.

PARAMETERS
-LiteralPath <string[]>
Specifies the path to be converted. The value of the LiteralPath parameter is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences.

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

-Path <string[]>
Specifies the Windows PowerShell path to be converted.

-UseTransaction [<SwitchParameter>]
Includes the command in the active transaction. This parameter is valid only when a transaction is in progress. For more information, see about_transactions.

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

INPUTS
System.String
You can pipe a path (but not a literal path) to Convert-Path.

OUTPUTS
System.String
Convert-Path returns a string that contains the converted path.

NOTES

The cmdlets that contain the Path noun (the Path cmdlets) manipulate path names and return the names in a concise format that all Windows PowerShell providers can interpret. They are designed for use in programs and scripts where you want to display all or part of a path name in a particular format. Use them like you would use Dirname, Normpath, Realpath, Join, or other path manipulators.

You can use the path cmdlets with several providers, including the FileSystem, Registry, and Certificate providers.

The Convert-Path cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, type “Get-PSProvider“. For more information, see about_providers.

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

C:\PS>Convert-Path ~

    Description
    ———–
    This command expands the current working directory.

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

C:\PS>Convert-Path HKLM:\software\microsoft

    Description
    ———–
    This command converts the Windows PowerShell provider path to a standard Registry path.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=113289
    about_providers
    Test-Path
    Split-Path
    Resolve-Path
    Join-Path

cmdlet, ConvertTo, Csv

ConvertTo-Csv

February 26, 2014 Adam

NAME
ConvertTo-Csv

SYNOPSIS
Converts Microsoft .NET Framework objects into a series of comma-separated value (CSV) Variable-length strings.

SYNTAX
ConvertTo-Csv [[-Delimiter] <char>] [-InputObject] <psobject> [-NoTypeInformation] [<CommonParameters>]

ConvertTo-Csv [-UseCulture] [-InputObject] <psobject> [-NoTypeInformation] [<CommonParameters>]

DESCRIPTION
The ConvertTo-Csv cmdlet returns a series of comma-separated, Variable-length (CSV) strings that represents the objects that you submit. You can then use the ConvertFrom-Csv cmdlet to re-create objects from the CSV strings. The resulting objects are CSV versions of the original objects that consist of string representations of the property values and no methods.

You can also use the Export-Csv and Import-Csv cmdlets to convert .NET Framework objects to CSV strings (and back). Export-Csv is the same as ConvertTo-Csv, except that it saves the CSV strings in a file.

You can use the parameters of the ConvertTo-Csv cmdlet to specify a delimiter other than a comma or to direct ConvertTo-Csv to use the default delimiter for the current culture.

For more information, see Export-Csv, and see the Notes section.

PARAMETERS
-Delimiter <char>
Specifies a delimiter to separate the property values. The default is a comma (,). Enter a character, such as a colon (:).

To specify a semicolon (;), enclose it in quotation marks. Otherwise, it will be interpreted as the command delimiter.

        Required?                    false
        Position?                    2
        Default value                , (comma)
        Accept pipeline input?     false
        Accept wildcard characters? false

-InputObject <psobject>
Specifies the objects to export as CSV strings. Enter a Variable that contains the objects or type a command or expression that gets the objects. You can also pipe objects to ConvertTo-Csv.

-NoTypeInformation [<SwitchParameter>]
Omits the type information header from the output. By default, the string in the output contains “#TYPE ” followed by the fully-qualified name of the type of the .NET Framework object.

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

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

This parameter is very useful in scripts that are being distributed to users worldwide. To find the list separator for a culture, use the following command: (Get-Culture).TextInfo.ListSeparator.

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

INPUTS
System.Management.Automation.PSObject
You can pipe any .NET Framework object to ConvertTo-Csv.

OUTPUTS
System.String
The CSV output is returned as a collection of strings.

NOTES

In CSV format, each object is represented by a comma-separated list of its property value. 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.

The format of the resulting CSV strings is as follows:

— The first string consists of ‘#TYPE ‘ followed by the fully-qualified name of the .NET Framework type of the object, such as #TYPE System.Diagnostics.Process. To suppress this string, use the NoTypeInformation parameter.

— The next string represents the column headers. It contains a comma-separated list of the names of all the properties of the first object.

— The remaining strings consist of comma-separated lists of the property values of each object.

When you submit multiple objects to ConvertTo-Csv, ConvertTo-Csv orders the strings based on the properties of the first object that you submit. If the remaining objects do not have one of the specified properties, the property value of that object is null, as represented by two consecutive commas. If the remaining objects have additional properties, those property values are ignored.

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

C:\PS>Get-Process powershell | ConvertTo-Csv

    #TYPE System.Diagnostics.Process
    “__NounName”,”Name”,”Handles”,”VM”,”WS”,”PM”,”NPM”,”Path”,”Company”,”CPU”,”FileVersion”,”ProductVersion”,”Description”,
    “Product”,”BasePriority”,”ExitCode”,”HasExited”,”ExitTime”,”Handle”,”HandleCount”,”Id”,”MachineName”,”MainWindowHandle”
    ,”MainWindowTitle”,”MainModule”,”MaxWorkingSet”,”MinWorkingSet”,”Modules”,”NonpagedSystemMemorySize”,”NonpagedSystemMem
    orySize64″,”PagedMemorySize”,”PagedMemorySize64″,”PagedSystemMemorySize”,”PagedSystemMemorySize64″,”PeakPagedMemorySize
    “,”PeakPagedMemorySize64″,”PeakWorkingSet”,”PeakWorkingSet64″,”PeakVirtualMemorySize”,”PeakVirtualMemorySize64″,”Priori
    tyBoostEnabled”,”PriorityClass”,”PrivateMemorySize”,”PrivateMemorySize64″,”PrivilegedProcessorTime”,”ProcessName”,”Proc
    essorAffinity”,”Responding”,”SessionId”,”StartInfo”,”StartTime”,”SynchronizingObject”,”Threads”,”TotalProcessorTime”,”U
    serProcessorTime”,”VirtualMemorySize”,”VirtualMemorySize64″,”EnableRaisingEvents”,”StandardInput”,”StandardOutput”,”Sta
    ndardError”,”WorkingSet”,”WorkingSet64″,”Site”,”Container”
    “Process”,”powershell”,”216″,”597544960″,”60399616″,”63197184″,”21692″,”C:\WINDOWS\system32\WindowsPowerShell\v1.0\powe
    rshell.exe”,”Microsoft Corporation”,”3.4788223″,”6.1.6587.1 (fbl_srv_powershell(nigels).070711-0102)”,”6.1.6587.1″,”Win
    dows PowerShell”,”Microsoft® Windows® Operating System”,”8″,,”False”,,”860″,”216″,”5132″,”.”,”5636936″,”Windows PowerSh
    ell 2.0 (04/17/2008 00:10:40)”,”System.Diagnostics.ProcessModule (powershell.exe)”,”1413120″,”204800″,”System.Diagnosti
    cs.ProcessModuleCollection”,”21692″,”21692″,”63197184″,”63197184″,”320080″,”320080″,”63868928″,”63868928″,”60715008″,”6
    0715008″,”598642688″,”598642688″,”True”,”Normal”,”63197184″,”63197184″,”00:00:00.2028013″,”powershell”,”15″,”True”,”1″,
    “System.Diagnostics.ProcessStartInfo”,”4/21/2008 3:49:19 PM”,,”System.Diagnostics.ProcessThreadCollection”,”00:00:03.51
    00225″,”00:00:03.3072212″,”597544960″,”597544960″,”False”,,,,”60399616″,”60399616″,,

    Description
    ———–
    This command converts a single process object to CSV format. The command uses the Get-Process cmdlet to get the PowerShell process on the local computer. It uses a pipeline operator (|) to send the command to the ConvertTo-Csv cmdlet, which converts it to a series of comma-separated strings.

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

C:\PS>$date = Get-Date

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

    Description
    ———–
    This example converts a date object to CSV format.

The first command uses the Get-Date cmdlet to get the current date. It saves it in the $date Variable.

The second command uses the ConvertTo-Csv cmdlet to convert the DateTime object in the $date Variable to CSV format. The command uses the InputObject parameter to specify the object to be converted. It uses the Delimiter parameter to specify the delimiter that separates the object properties. It uses the NoTypeInformation parameter to suppress the #TYPE string.

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

C:\PS>Get-Eventlog -log “windows powershell” | ConvertTo-Csv -useculture

    Description
    ———–
    This command converts the Windows PowerShell event log on the local computer to a series of CSV strings.

The command uses the Get-EventLog cmdlet to get the events in the Windows PowerShell log. A pipeline operator (|) sends the events to the ConvertTo-Csv cmdlet, which converts the events to CSV format. The command uses the UseCulture parameter, which uses the list separator for the current culture as the delimiter.

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

cmdlet, ConvertFrom, Csv

ConvertFrom-Csv

February 26, 2014 Adam

NAME
ConvertFrom-Csv

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.

-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

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