All posts by Adam

cmdlet, ConvertTo, Xml

ConvertTo-Xml

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

    <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.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, ConvertTo, SecureString

ConvertTo-SecureString

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

    <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 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 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 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, ConvertTo, Html

ConvertTo-Html

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.

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

    -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

    <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.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, Csv

ConvertTo-Csv

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.

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

    -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

    <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.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, Convert, Path

Convert-Path

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.

        Required?                    true
        Position?                    1
        Default value
        Accept pipeline input?     true (ByValue, ByPropertyName)
        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

    <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 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, ConvertFrom, StringData

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

cmdlet, ConvertFrom, SecureString

ConvertFrom-SecureString

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

    <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.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, Csv

ConvertFrom-Csv

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.

        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, Connect, WSMan

Connect-WSMan

NAME
    Connect-WSMan

SYNOPSIS
    Connects to the WinRM service on a remote computer.

SYNTAX
    Connect-WSMan [-ApplicationName <string>] [-ComputerName <string>] [-Port <int>] [-UseSSL] [-Authentication <Authentication>] [-ComputerName <string>] [-Credential <PSCredential>] [-Port <int>] [-SessionOption <hashtable>] [<CommonParameters>]

    Connect-WSMan [-ConnectionURI <Uri>] [-Authentication <Authentication>] [-ComputerName <string>] [-Credential <PSCredential>] [-Port <int>] [-SessionOption <hashtable>] [<CommonParameters>]

DESCRIPTION
    The Connect-WSMan cmdlet connects to the WinRM service on a remote computer, and it establishes a persistent connection to the remote computer. You can use this cmdlet within the context of the WS-Management provider to connect to the WinRM service on a remote computer. However, you can also use this cmdlet to connect to the WinRM service on a remote computer before you change to the WS-Management provider. The remote computer will appear in the root directory of the WS-Management provider.

    For more information about how to disconnect from the WinRM service on a remote computer, see Disconnect-WSMan.

PARAMETERS
    -ApplicationName <string>
        Specifies the application name in the connection. The default value of the ApplicationName parameter is “WSMAN”. The complete identifier for the remote endpoint is in the following format:
             <transport>://<server>:<port>/<ApplicationName>
        For example:
             http://server01:8080/WSMAN

        Internet Information Services (IIS), which hosts the session, forwards requests with this endpoint to the specified application. This default setting of “WSMAN” is appropriate for most uses. This parameter is designed to be used when numerous computers establish remote connections to one computer that is running Windows PowerShell. In this case, IIS hosts Web Services for Management (WS-Management) for efficiency.

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

    -Authentication <Authentication>
        Specifies the authentication mechanism to be used at the server. Possible values are:

        – Basic: Basic is a scheme in which the user name and password are sent in clear text to the server or proxy.
        – Default : Use the authentication method implemented by the WS-Management protocol. This is the default.
        – Digest: Digest is a challenge-response scheme that uses a server-specified data string for the challenge.
        – Kerberos: The client computer and the server mutually authenticate by using Kerberos Certificates.
        – Negotiate: Negotiate is a challenge-response scheme that negotiates with the server or proxy to determine the scheme to use for authentication. For example, this parameter value allows negotiation to determine whether the Kerberos protocol or NTLM is used.
        – CredSSP: Use Credential Security Service Provider (CredSSP) authentication, which allows the user to delegate credentials. This option is designed for commands that run on one remote computer but collect data from or run additional commands on other remote computers.

        Caution: CredSSP delegates the user’s credentials from the local computer to a remote computer. This practice increases the security risk of the remote operation. If the remote computer is compromised, when credentials are passed to it, the credentials can be used to control the network session.

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

    -ComputerName <string>
        Specifies the computer against which you want to run the management operation. The value can be a fully qualified domain name, a NetBIOS name, or an IP address. Use the local computer name, use localhost, or use a dot (.) to specify the local computer. The local computer is the default. When the remote computer is in a different domain from the user, you must use a fully qualified domain name must be used. You can pipe a value for this parameter to the cmdlet.

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

    -ConnectionURI <Uri>
        Specifies the connection endpoint. The format of this string is:

             <Transport>://<Server>:<Port>/<ApplicationName>.

        The following string is a properly formatted value for this parameter:

             http://Server01:8080/WSMAN. The URI must be fully qualified .

        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”, “Domain01\User01”, or “User@Domain.com”. Or, enter a PSCredential object, such as one returned by the Get-Credential cmdlet. When you type a user name, you will be prompted for a password.

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

    -OptionSet <hashtable>
        Passes a set of switches to the service to modify or refine the nature of the request. These are similar to switches used in command-line shells in that they are service specific. Any number of options can be specified.

        The following example demonstrates the syntax that passes the values 1, 2, and 3 for the a, b, and c parameters:

             -OptionSet @{a=1;b=2;c=3}

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

    -Port <int>
        Specifies the port to use when the client connects to the WinRM service. When the transport is HTTP, the default port is 80. When the transport is HTTPS, the default port is 443. When you use HTTPS as the transport, the value of the ComputerName parameter must match the server’s Certificate common name (CN). However, if the SkipCNCheck parameter is specified as part of the SessionOption parameter, then the Certificate common name of the server does not have to match the host name of the server. The SkipCNCheck parameter should be used only for trusted computers.

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

    -SessionOption <hashtable>
        Defines a set of extended options for the WS-Management session. Enter a SessionOption object that you create by using the New-WSManSessionOption cmdlet. For more information about the options that are available, see New-WSManSessionOption.

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

    -UseSSL [<SwitchParameter>]
        Specifies that the Secure Sockets Layer (SSL) protocol should be used to establish a connection to the remote computer. By default, SSL is not used.

        WS-Management encrypts all the Windows PowerShell content that is transmitted over the network. The UseSSL parameter lets you specify the additional protection of HTTPS instead of HTTP. If SSL is not available on the port that is used for the connection and you specify this parameter, the command fails.

        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
        This cmdlet does not accept any input.

OUTPUTS
    None
        This cmdlet does not generate any output.

NOTES

        You can run management commands or query management data on a remote computer without creating a WS-Management session. You can do this by using the ComputerName parameters of Invoke-WSManAction and Get-WSManInstance. When you use the ComputerName parameter, Windows PowerShell creates a temporary connection that is used for the single command. After the command runs, the connection is closed.

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

    C:\PS>Connect-WSMan -computer server01

    PS C:\Users\testuser> cd WSMan:
    PS WSMan:\>
    PS WSMan:\> dir

     WSManConfig: Microsoft.WSMan.Management\WSMan::WSMan

    ComputerName                                 Type
    ————                                 —-
    localhost                                     Container
    server01                                     Container

    Description
    ———–
    This command creates a connection to the remote server01 computer.

    The Connect-WSMan cmdlet is generally used within the context of the WS-Management provider to connect to a remote computer, in this case the server01 computer. However, you can use the cmdlet to establish connections to remote computers before you change to the WS-Management provider. Those connections will appear in the ComputerName list.

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

    C:\PS>$cred = Get-Credential Administrator
    Connect-WSMan -computer server01 -Credential $cred

    PS C:\Users\testuser> cd WSMan:
    PS WSMan:\>
    PS WSMan:\> dir

     WSManConfig: Microsoft.WSMan.Management\WSMan::WSMan

    ComputerName                                 Type
    ————                                 —-
    localhost                                     Container
    server01                                     Container

    Description
    ———–
    This command creates a connection to the remote system server01 using the Administrator account credentials.

    The first command uses the Get-Credential cmdlet to get the Administrator credentials and then stores them in the $cred Variable. The Get-Credential cmdlet prompts the user for a password of username and password. Users are prompted throught a dialog box
    or at the command line, depending on system Registry settings.

    The second command uses the Credential parameter to pass the credentials stored in $cred to Connect-WSMan. Connect-WSMan then connects to the remote system server01 using the Administrator credentials.

    The Connect-WSMan cmdlet is generally used within the context of the WS-Management provider to connect to a remote computer, in this case server01. However, the cmdlet can be used establish connections to remote computers before changing to the WS-Management provider and those connections will show up in the ComputerName list.

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

    C:\PS>Connect-WSMan -computer server01 -Port 80

    PS C:\Users\testuser> cd WSMan:
    PS WSMan:\>
    PS WSMan:\> dir

     WSManConfig: Microsoft.WSMan.Management\WSMan::WSMan

    ComputerName                                 Type
    ————                                 —-
    localhost                                     Container
    server01                                     Container

    Description
    ———–
    This command creates a connection to the remote server01 computer over port 80.

    The Connect-WSMan cmdlet is generally used within the context of the WS-Management provider to connect to a remote computer, in this case the server01 computer. However, you can use the cmdlet to establish connections to remote computers before you change to the WS-Management provider. Those connections will appear in the ComputerName list.

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

    C:\PS>$a = New-WSManSessionOption -operationtimeout 30000
    Connect-WSMan -computer server01 -SessionOption $a

    PS C:\Users\testuser> cd WSMan:
    PS WSMan:\>
    PS WSMan:\> dir

     WSManConfig: Microsoft.WSMan.Management\WSMan::WSMan

    ComputerName                                 Type
    ————                                 —-
    localhost                                     Container
    server01                                     Container

    Description
    ———–
    This command creates a connection to the remote server01 computer by using the connection options that are defined in the New-WSManSessionOption command.

    The first command uses the New-WSManSessionOption cmdlet to store a set of connection setting options in the $a Variable. In this case, the session options set a connection time out of 30 seconds (30,000 milliseconds).

    The second command uses the SessionOption parameter to pass the credentials that are stored in the $a Variable to Connect-WSMan. Then, Connect-WSMan connects to the remote server01 computer by using the specified session options.

    The Connect-WSMan cmdlet is generally used within the context of the WS-Management provider to connect to a remote computer, in this case the server01 computer. However, you can use the cmdlet to establish connections to remote computers before you change to the WS-Management provider. Those connections will appear in the ComputerName list.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkId=141437
    Disable-WSManCredSSP
    Disconnect-WSMan
    Enable-WSManCredSSP
    Get-WSManCredSSP
    Get-WSManInstance
    Invoke-WSManAction
    New-WSManInstance
    New-WSManSessionOption
    Remove-WSManInstance
    Set-WSManInstance
    Set-WSManQuickConfig
    Test-WSMan

cmdlet, Complete, Transaction

Complete-Transaction

NAME
    Complete-Transaction

SYNOPSIS
    Commits the active transaction.

SYNTAX
    Complete-Transaction [-Confirm] [-WhatIf] [<CommonParameters>]

DESCRIPTION
    The Complete-Transaction cmdlet commits an active transaction. When you commit a transaction, the commands in the transaction are finalized and the data affected by the commands is changed.

    If the transaction includes multiple subscribers, to commit the transaction, you must enter one Complete-Transaction command for every Start-Transaction command.

    The Complete-Transaction cmdlet is one of a set of cmdlets that support the transactions feature in Windows PowerShell. For more information, see about_transactions.

PARAMETERS
    -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 objects to Complete-Transaction.

OUTPUTS
    None
        This cmdlet does not return any objects.

NOTES

        You cannot roll back a transaction that has been committed, or commit a transaction that has been rolled back.

        You cannot roll back any transaction other than the active transaction. To roll back a different transaction, you must first commit or roll back the active transaction.

        By default, if any part of a transaction cannot be committed, such as when a command in the transaction results in an error, the entire transaction is rolled back.

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

    C:\PS>cd hkcu:\software

    PS HKCU:\software> Start-Transaction

    PS HKCU:\software> New-Item MyCompany -UseTransaction
    PS HKCU:\software> dir m*

     Hive: HKEY_CURRENT_USER\software

    SKC VC Name                         Property
    — — —-                         ——–
     82 1 Microsoft                     {(default)}

    PS HKCU:\software> Complete-Transaction
    PS HKCU:\software> dir m*

     Hive: HKEY_CURRENT_USER\Software

    SKC VC Name                         Property
    — — —-                         ——–
     82 1 Microsoft                     {(default)}
     0 0 MyCompany                     {}

    Description
    ———–
    This example shows the effect of using the Complete-Transaction cmdlet to commit a transaction.

    The Start-Transaction command starts the transaction. The New-Item command uses the UseTransaction parameter to include the command in the transaction.

    The first “dir” (Get-ChildItem) command shows that the new item has not yet been added to the Registry.

    The Complete-Transaction command commits the transaction, which makes the Registry change effective. As a result, the second “dir” command shows that the Registry is changed.

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

    C:\PS>cd hkcu:\software

    PS HKCU:\software> Start-Transaction
    PS HKCU:\software> New-Item MyCompany -UseTransaction

     Hive: HKEY_CURRENT_USER\Software

    SKC VC Name                         Property
    — — —-                         ——–
     0 0 MyCompany                     {}

    PS HKCU:\software> Start-Transaction
    PS HKCU:\Software> Get-Transaction

    RollbackPreference SubscriberCount Status
    —————— ————— ——
    Error                2                Active

    PS HKCU:\software> New-Itemproperty -path MyCompany -name MyKey -value -UseTransaction

    MyKey
    —–
    123

    PS HKCU:\software> Complete-Transaction
    PS HKCU:\software> Get-Transaction

    RollbackPreference SubscriberCount Status
    —————— ————— ——
    Error                1                Active

    PS HKCU:\software> dir m*

     Hive: HKEY_CURRENT_USER\Software

    SKC VC Name                         Property
    — — —-                         ——–
     82 1 Microsoft                     {(default)}

    PS HKCU:\software> Complete-Transaction
    PS HKCU:\software> dir m*

     Hive: HKEY_CURRENT_USER\Software

    SKC VC Name                         Property
    — — —-                         ——–
     82 1 Microsoft                     {(default)}
     0 1 MyCompany                     {MyKey}

    Description
    ———–
    This example shows how to use Complete-Transaction to commit a transaction that has more than one subscriber.

    To commit a multi-subscriber transaction, you must enter one Complete-Transaction command for every Start-Transaction command. The data is changed only when the final Complete-Transaction command is submitted.

    For demonstration purposes, this example shows a series of commands entered at the command line. In practice, transactions are likely to be run in scripts, with the secondary transaction being run by a Function or helper script that is called by the main script.

    In this example, a Start-Transaction command starts the transaction. A New-Item command with the UseTransaction parameter adds the MyCompany key to the Software key. Although the New-Item command returns a key object, the data in the Registry is not yet changed.

    A second Start-Transaction command adds a second subscriber to the existing transaction. The Get-Transaction command confirms that the subscriber count is 2. A New-ItemProperty command with the UseTransaction parameter adds a Registry entry to the new MyCompany key. Again, the command returns a value, but the Registry is not changed.

    The first Complete-Transaction command reduces the subscriber count by 1. This is confirmed by a Get-Transaction command. However, no data is changed, as evidenced by a “dir m*” (Get-ChildItem) command.

    The second Complete-Transaction command commits the entire transaction and changes the data in the Registry. This is confirmed by a second “dir m*” command, which shows the changes.

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

    C:\PS>cd hkcu:\software

    PS HKCU:\software> Start-Transaction

    PS HKCU:\software> New-Item MyCompany -UseTransaction

    PS HKCU:\software> dir m*

     Hive: HKEY_CURRENT_USER\Software

    SKC VC Name                         Property
    — — —-                         ——–
     82 1 Microsoft                     {(default)}

    PS HKCU:\software> dir m* -UseTransaction

     Hive: HKEY_CURRENT_USER\Software

    SKC VC Name                         Property
    — — —-                         ——–
     82 1 Microsoft                     {(default)}
     0 0 MyCompany                     {}

    PS HKCU:\software> Complete-Transaction

    Description
    ———–
    This example shows the value of using Get-* commands, and other commands that do not change data, in a transaction. When a Get-* command is used in a transaction, it gets the objects that are part of the transaction. This allows you to preview the changes in the transaction before the changes are committed.

    In this example, a transaction is started. A New-Item command with the UseTransaction parameter adds a new key to the Registry as part of the transaction.

    Because the new Registry key is not added to the Registry until the Complete-Transaction command is run, a simple “dir” (Get-ChildItem) command shows the Registry without the new key.

    However, when you add the UseTransaction parameter to the “dir” command, the command becomes part of the transaction, and it gets the items in the transaction even if they are not yet added to the data.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=135200
    about_transactions
    Start-Transaction
    Get-Transaction
    Undo-Transaction
    Use-Transaction