Category Archives: List

cmdlet, List, Update

Update-List

NAME
    Update-List

SYNOPSIS
    Adds items to and removes items from a property value that contains a collection of objects.

SYNTAX
    Update-List [-Add <Object[]>] [-Remove <Object[]>] [[-Property] <string>] [-InputObject <psobject>] [<CommonParameters>]

    Update-List -Replace <Object[]> [[-Property] <string>] [-InputObject <psobject>] [<CommonParameters>]

DESCRIPTION
    The Update-List cmdlet adds items to and removes items from a property value of an object, and then it returns the updated object. This cmdlet is designed for properties that contain collections of objects.

    The Add and Remove parameters add individual items to and remove them from the collection. The Replace parameter replaces the entire collection.

    If you do not specify a property in the command, Update-List returns an object that describes the update instead of updating the object. You can submit the update object to cmdlets that change objects, such as Set-* cmdlets.

    This cmdlet works only when the property that is being updated supports the IList interface that Update-List uses. Also, any Set-* cmdlets that accept an update must support the IList interface. The core cmdlets that are installed with Windows PowerShell do not support this interface. To determine whether a cmdlet supports Update-List, see the cmdlet Help topic.

PARAMETERS
    -Add <Object[]>
        Specifies the property values to be added to the collection. Enter the values in the order that they should appear in the collection.

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

    -InputObject <psobject>
        Specifies the objects to be updated. You can also pipe the object to be updated to Update-List.

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

    -Property <string>
        Identifies the property that contains the collection that is being updated. If you omit this parameter, Update-List returns an object that represents the change instead of changing the object.

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

    -Remove <Object[]>
        Specifies the property values to be removed from the collection.

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

    -Replace <Object[]>
        Specifies a new collection. This parameter replaces all items in the original collection with the items specified by this parameter.

        Required?                    true
        Position?                    named
        Default value                None
        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 the objects to be updated to Update-List.

OUTPUTS
    Objects or System.Management.Automation.PSListModifier
        Update-List returns the updated object, or it returns an object that represents the update action.

NOTES

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

    C:\PS>get-mailbox | Update-List -Property Aliases -Add “A”,”B” -Remove “X”,”Y” | set-mailbox

    Description
    ———–
    This command adds A and B and removes X and Y from the Aliases property of a mailbox.

    The command uses the Get-MailBox cmdlet from Microsoft Exchange Server to get the mailbox. A pipeline operator sends the mailbox object to the Update-List cmdlet.

    The Update-List command uses the Property parameter to indicate that the Aliases property of the mailbox is being updated, and it uses the Add and Remove parameters to specify the items that are being added and removed from the collection. The Aliases property fulfills the conditions of Update-List, because it stores a collection of Microsoft .NET Framework objects that have Add and Remove methods.

    The Update-List cmdlet returns the updated mailbox, which is piped to the Set-MailBox cmdlet, which changes the mailbox.

    For more information about Get-Mailbox, see http://go.microsoft.com/fwlink/?LinkId=111536.

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

    C:\PS>$m = get-mailbox

    C:\PS> Update-List -InputObject $m -Property Aliases -Add “A”,”B” -Remove “X”, “Y” | set-mailbox

    Description
    ———–
    This command adds A and B to the value of the Aliases property of a mailbox and removes X and Y. This command has the same effect as the previous command, although it has a slightly different format.

    The command uses the Get-MailBox cmdlet to get the mailbox, and it saves the mailbox in the $m Variable. This command uses the InputObject parameter of Update-List to specify the mailbox. The value of InputObject is the mailbox in the $m Variable. It uses the Property parameter to specify the Aliases property and the Add and Remove parameters to specify the items being added to and removed from the value of Aliases.

    The command uses a pipeline operator (|) to send the updated mailbox object to the Set-Mailbox cmdlet, which changes the mailbox.

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

    C:\PS>get-mailbox | set-mailbox -alias (Update-List -Add “A”, “B” -Remove “X”,”Y”)

    Description
    ———–
    This command adds A and B to the value of the Aliases property of a mailbox and removes X and Y. This command has the same effect as the two previous commands, but it uses a different procedure to perform the task.

    Instead of updating the Aliases property of the mailbox before sending it to Set-Mailbox, this command uses Update-List to create an object that represents the change. Then it submits the change to the Alias parameter of Set-Mailbox.

    The command uses the Get-MailBox cmdlet to get the mailbox. A pipeline operator sends the mailbox object to the Set-Mailbox cmdlet, which changes mailboxes.

    The command uses the Alias parameter of Set-Mailbox to change the Aliases property of the mailbox object. The value of the Alias parameter is an Update-List command that creates an object that represents the update. The Update-List command is enclosed in parentheses to ensure that it runs before the value of the Alias parameter is evaluated. When the Set-Mailbox command completes, the mailbox is changed.

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

    C:\PS>Update-List -InputObject $a -Property Aliases -replace “A”, “B” | set-mailbox

    Description
    ———–
    This command uses the Replace operator of Update-List to replace the collection in the Aliases property of the object in $a with a new collection.

    This command uses the InputObject parameter which, in this case, is equivalent to using a pipeline operator to pass $a to Update-List.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=113447
    Select-Object

cmdlet, Format, List

Format-List

NAME
    Format-List

SYNOPSIS
    Formats the output as a list of properties in which each property appears on a new line.

SYNTAX
    Format-List [[-Property] <Object[]>] [-DisplayError] [-Expand <string>] [-Force] [-GroupBy <Object>] [-InputObject <psobject>] [-ShowError] [-View <string>] [<CommonParameters>]

DESCRIPTION
    The Format-List cmdlet formats the output of a command as a list of properties in which each property is displayed on a separate line. You can use Format-List to format and display all or selected properties of an object as a list (Format-List *).

    Because more space is available for each item in a list than in a table, Windows PowerShell displays more properties of the object in the list, and the property values are less likely to be truncated.

PARAMETERS
    -DisplayError [<SwitchParameter>]
        Displays errors at the command line.

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

    -Expand <string>
        Formats the collection object, as well as the objects in the collection. This parameter is designed to format objects that support the ICollection (System.Collections) interface. The default value is EnumOnly.

        Valid values are:
        — EnumOnly: Displays the properties of the objects in the collection.
        — CoreOnly: Displays the properties of the collection object.
        — Both: Displays the properties of the collection object and the properties of objects in the collection.

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

    -Force [<SwitchParameter>]
        Directs the cmdlet to display all of the error information. Use with the DisplayError or ShowError parameters. By default, when an error object is written to the error or display streams, only some of the error information is displayed.

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

    -GroupBy <Object>
        Formats the output in groups based on a shared property or value. Enter an expression or a property of the output.

        The value of the GroupBy parameter can be a new calculated property. To create a calculated, property, use a hash table. Valid keys are:

        — Name (or Label) <string>
        — Expression <string> or <script block>
        — FormatString <string>

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

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

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

    -Property <Object[]>
        Specifies the object properties that appear in the display and the order in which they appear. Wildcards are permitted.

        If you omit this parameter, the properties that appear in the display depend on the object being displayed. The parameter name (“Property”) is optional. You cannot use the Property and View parameters in the same command.

        The value of the Property parameter can be a new calculated property. To create a calculated, property, use a hash table. Valid keys are:

        — Name (or Label) <string>
        — Expression <string> or <script block>
        — FormatString <string>

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

    -ShowError [<SwitchParameter>]
        Sends errors through the pipeline.

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

    -View <string>
        Specifies the name of an alternate list format or “view.” You cannot use the Property and View parameters in the same 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
    System.Management.Automation.PSObject
        You can pipe any object to Format-List.

OUTPUTS
    Microsoft.PowerShell.Commands.Internal.Format
        Format-List returns the format objects that represent the list.

NOTES

        You can also refer to Format-List by its built-in Alias, “FL”. For more information, see about_aliases.

        The format cmdlets, such as Format-List, arrange the data to be displayed but do not display it. The data is displayed by the output features of Windows PowerShell and by the cmdlets that contain the Out verb (the Out cmdlets), such as Out-Host, Out-File, and Out-Printer.

        If you do not use a format cmdlet, Windows PowerShell applies that default format for each object that it displays.

        The GroupBy parameter assumes that the objects are sorted. Before using Format-Custom to group the objects, use Sort-Object to sort them.

        The View parameter lets you specify an alternate format for the table. You can use the views defined in the *.format.PS1XML files in the Windows PowerShell directory, or you can create your own views in new PS1XML files and use the Update-FormatData cmdlet to include them in Windows PowerShell.

        The alternate view for the View parameter must use the list format; if not, the command fails. If the alternate view is a table, use Format-Table. If the alternate view is neither a list nor a table, use Format-Custom.

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

    C:\PS>Get-Service | Format-List

    Description
    ———–
    This command formats information about services on the computer as a list. By default, the services are formatted as a table. The Get-Service cmdlet gets objects representing the services on the computer. The pipeline operator (|) passes the results through the pipeline to Format-List. Then, the Format-List command formats the service information in a list and sends it to the default output cmdlet for display.

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

    C:\PS>$a = Get-ChildItem $pshome\*.ps1xml

    Description
    ———–
    These commands display information about the PS1XML files in the Windows PowerShell directory as a list. The first command gets the objects representing the files and stores them in the $a Variable. The second command uses Format-List to format information about objects stored in $a. This command uses the InputObject parameter to pass the Variable to Format-List, which then sends the formatted output to the default output cmdlet for display.

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

    C:\PS>Get-Process | Format-List -Property name, basepriority, priorityclass

    Description
    ———–
    This command displays the name, base priority, and priority class of each process on the computer. It uses the Get-Process cmdlet to get an object representing each process. The pipeline operator (|) passes the process objects through the pipeline to Format-List. Format-List formats the processes as a list of the specified properties. The “Property” parameter name is optional, so you can omit it.

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

    C:\PS>Get-Process winlogon | Format-List -Property *

    Description
    ———–
    This command displays all of the properties of the Winlogon process. It uses the Get-Process cmdlet to get an object representing the Winlogon process. The pipeline operator (|) passes the Winlogon process object through the pipeline to Format-List. The command uses the Property parameter to specify the properties and the * to indicate all properties. Because the name of the Property parameter is optional, you can omit it and type the command as: “Format-List *”. Format-List automatically sends the results to the default output cmdlet for display.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=113302