Partilhar via

Update-List

Módulo:
Microsoft.PowerShell.Utility Module

Adiciona itens e remove itens de um valor de propriedade que contém uma coleção de objetos.

Sintaxe

AddRemoveSet (Predefinição) 

Update-List
    [[-Property] <String>]
    [-Add <Object[]>]
    [-Remove <Object[]>]
    [-InputObject <PSObject>]
    [<CommonParameters>]

ReplaceSet 

Update-List
    [[-Property] <String>]
    -Replace <Object[]>
    [-InputObject <PSObject>]
    [<CommonParameters>]

Description

O cmdlet Update-List adiciona, remove ou substitui itens em um valor de propriedade de um objeto e retorna o objeto atualizado. Este cmdlet foi projetado para propriedades que contêm coleções de objetos.

Os parâmetros Adicionar e Remover adicionar itens individuais e removê-los da coleção. O parâmetro Replace substitui toda a coleção.

Se você não especificar uma propriedade no comando, Update-List retornará uma hashtable que descreve a atualização em vez de atualizar o objeto. Mais tarde, você pode usar esse conjunto de alterações para atualizar um objeto de lista.

Esse cmdlet funciona somente quando a propriedade que está sendo atualizada oferece suporte à interface IList que Update-List usa. Além disso, todos os cmdlets Set que aceitam uma atualização devem oferecer suporte à interface IList.

Este cmdlet foi reintroduzido no PowerShell 7.

Exemplos

Exemplo 1: Adicionar itens a um valor de propriedade

Neste exemplo, criamos uma classe que representa um baralho de cartas onde as cartas são armazenadas como um objeto List collection. O método NewDeck() usa Update-Listpara adicionar um baralho completo de valores de cartas à coleção Cards.

class Cards {

    [System.Collections.Generic.List[string]]$Cards
    [string]$Name

    Cards([string]$_name) {
        $this.Name = $_name
        $this.Cards = [System.Collections.Generic.List[string]]::new()
    }

    NewDeck() {
        $_suits = "`u{2663}","`u{2666}","`u{2665}","`u{2660}"
        $_values = 'A',2,3,4,5,6,7,8,9,10,'J','Q','K'
        $_deck = foreach ($s in $_suits){ foreach ($v in $_values){ "$v$s"} }
        $this | Update-List -Property Cards -Add $_deck | Out-Null
    }

    Show() {
        Write-Host
        Write-Host $this.Name ": " $this.Cards[0..12]
        if ($this.Cards.Count -gt 13) {
            Write-Host (' ' * ($this.Name.Length+3)) $this.Cards[13..25]
        }
        if ($this.Cards.Count -gt 26) {
            Write-Host (' ' * ($this.Name.Length+3)) $this.Cards[26..38]
        }
        if ($this.Cards.Count -gt 39) {
            Write-Host (' ' * ($this.Name.Length+3)) $this.Cards[39..51]
        }
    }

    Shuffle() { $this.Cards = Get-Random -InputObject $this.Cards -Count 52 }

    Sort() { $this.Cards.Sort() }
}

Observação

O cmdlet Update-List envia o objeto atualizado para o pipeline. Nós canalizamos a saída para Out-Null para suprimir a exibição indesejada.

Exemplo 2: Adicionar e remover itens de uma propriedade de coleção

Continuando com o código no Exemplo 1, criaremos instâncias da classe Cards para representar um baralho de cartas e as cartas mantidas por dois jogadores. Usamos o cmdlet Update-List para adicionar cartas às mãos dos jogadores e remover cartas do baralho.

$player1 = [Cards]::new('Player 1')
$player2 = [Cards]::new('Player 2')

$deck = [Cards]::new('Deck')
$deck.NewDeck()
$deck.Shuffle()
$deck.Show()

# Deal two hands
$player1 | Update-List -Property Cards -Add $deck.Cards[0,2,4,6,8] | Out-Null
$player2 | Update-List -Property Cards -Add $deck.Cards[1,3,5,7,9] | Out-Null
$deck | Update-List -Property Cards -Remove $player1.Cards | Out-Null
$deck | Update-List -Property Cards -Remove $player2.Cards | Out-Null

$player1.Show()
$player2.Show()
$deck.Show()

Deck :  4♦ 7♥ J♦ 5♣ A♣ 8♦ J♣ Q♥ 6♦ 3♦ 9♦ 6♣ 2♣
        K♥ 4♠ 10♥ 8♠ 10♦ 9♠ 6♠ K♦ 7♣ 3♣ Q♣ A♥ Q♠
        3♥ 5♥ 2♦ 5♠ J♥ J♠ 10♣ 4♥ Q♦ 10♠ 4♣ 2♠ 2♥
        6♥ 7♦ A♠ 5♦ 8♣ 9♥ K♠ 7♠ 3♠ 9♣ A♦ K♣ 8♥

Player 1 :  4♦ J♦ A♣ J♣ 6♦

Player 2 :  7♥ 5♣ 8♦ Q♥ 3♦

Deck :  9♦ 6♣ 2♣ K♥ 4♠ 10♥ 8♠ 10♦ 9♠ 6♠ K♦ 7♣ 3♣
        Q♣ A♥ Q♠ 3♥ 5♥ 2♦ 5♠ J♥ J♠ 10♣ 4♥ Q♦ 10♠
        4♣ 2♠ 2♥ 6♥ 7♦ A♠ 5♦ 8♣ 9♥ K♠ 7♠ 3♠ 9♣
        A♦ K♣ 8♥

A saída mostra o estado do baralho antes das cartas serem distribuídas aos jogadores. Você pode ver que cada jogador recebeu cinco cartas do baralho. A saída final mostra o estado do baralho depois de distribuir as cartas aos jogadores. Update-List foi usado para selecionar as cartas do baralho e adicioná-las à coleção dos jogadores. Em seguida, as cartas dos jogadores foram removidas do baralho usando Update-List.

Exemplo 3: Adicionar e remover itens em um único comando

Update-List permite que você use a Adicionar e Remover parâmetros em um único comando. Neste exemplo, o Jogador 1 quer descartar o 4♦ e 6♦ e obter duas novas cartas.

# Player 1 wants two new cards - remove 2 cards & add 2 cards
$player1 | Update-List -Property Cards -Remove $player1.Cards[0,4] -Add $deck.Cards[0..1] | Out-Null
$player1.Show()

# remove dealt cards from deck
$deck | Update-List -Property Cards -Remove $deck.Cards[0..1] | Out-Null
$deck.Show()

Player 1 :  J♦ A♣ J♣ 9♦ 6♣

Deck :  2♣ K♥ 4♠ 10♥ 8♠ 10♦ 9♠ 6♠ K♦ 7♣ 3♣ Q♣ A♥
        Q♠ 3♥ 5♥ 2♦ 5♠ J♥ J♠ 10♣ 4♥ Q♦ 10♠ 4♣ 2♠
        2♥ 6♥ 7♦ A♠ 5♦ 8♣ 9♥ K♠ 7♠ 3♠ 9♣ A♦ K♣
        8♥

Exemplo 4: Aplicar um conjunto de alterações a um objeto de lista

Se você não especificar uma propriedade, Update-List retornará uma hashtable que descreve a atualização em vez de atualizar o objeto. Você pode converter a hashtable em um objeto System.PSListModifier e usar o método ApplyTo() para aplicar o conjunto de alterações a uma lista.

$list = [System.Collections.ArrayList] (1, 43, 2)
$changeInstructions = Update-List -Remove 43 -Add 42
$changeInstructions

Name                           Value
----                           -----
Add                            {42}
Remove                         {43}

([pslistmodifier]($changeInstructions)).ApplyTo($list)
$list

1
2
42

Parâmetros

-Add

Especifica os valores de propriedade a serem adicionados à coleção. Insira os valores na ordem em que devem aparecer na coleção.

Propriedades dos parâmetros

Tipo:

Object[]

Default value:None
Suporta carateres universais:False
NãoMostrar:False

Conjuntos de parâmetros

AddRemoveSet
Position:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos:False

-InputObject

Especifica os objetos a serem atualizados. Você também pode canalizar o objeto a ser atualizado para Update-List.

Propriedades dos parâmetros

Tipo:PSObject
Default value:None
Suporta carateres universais:False
NãoMostrar:False

Conjuntos de parâmetros

(All)
Position:Named
Obrigatório:False
Valor do pipeline:True
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos:False

-Property

Especifica a propriedade que contém a coleção que está sendo atualizada. Se você omitir esse parâmetro, Update-List retorna um objeto que representa a alteração em vez de alterar o objeto.

Propriedades dos parâmetros

Tipo:String
Default value:None
Suporta carateres universais:False
NãoMostrar:False

Conjuntos de parâmetros

(All)
Position:0
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos:False

-Remove

Especifica os valores de propriedade a serem removidos da coleção.

Propriedades dos parâmetros

Tipo:

Object[]

Default value:None
Suporta carateres universais:False
NãoMostrar:False

Conjuntos de parâmetros

AddRemoveSet
Position:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos:False

-Replace

Especifica uma nova coleção. Este parâmetro substitui todos os itens da coleção original pelos itens especificados por esse parâmetro.

Propriedades dos parâmetros

Tipo:

Object[]

Default value:None
Suporta carateres universais:False
NãoMostrar:False

Conjuntos de parâmetros

ReplaceSet
Position:Named
Obrigatório:True
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos:False

CommonParameters

Este cmdlet suporta os parâmetros comuns: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction e -WarningVariable. Para obter mais informações, consulte about_CommonParameters.

Entradas

PSObject

Você pode canalizar o objeto a ser atualizado para este cmdlet.

Saídas

Hashtable

Por padrão, esse cmdlet retorna uma hashtable que descreve a atualização.

Object

Quando você especifica o parâmetro Property, esse cmdlet retorna o objeto atualizado.