Partilhar via

Update-List

  • Referência
Módulo:
Microsoft.PowerShell.Utility

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

Sintaxe

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

Description

O Update-List cmdlet 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 adicionam itens individuais e os removem 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 usada Update-List . Além disso, todos os Set cmdlets 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 de coleção List . O método NewDeck() é usado Update-Listpara adicionar um baralho completo de valores de cartas à coleção de cartas .

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() }
}

Nota

O Update-List cmdlet envia o objeto atualizado para o pipeline. Nós canalizamos a saída para Out-Null 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 Update-List cmdlet 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 os parâmetros Adicionar e Remover 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 descreva a atualização em vez de atualizar o objeto. Você pode converter a hashtable em um objeto System.PSListModifier e usar o ApplyTo() método 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.

Tipo:Object[]
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-InputObject

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

Tipo:PSObject
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:True
Aceitar carateres universais:False

-Property

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

Tipo:String
Position:0
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-Remove

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

Tipo:Object[]
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais: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.

Tipo:Object[]
Position:Named
Default value:None
Necessário:True
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

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.