Update-List

模組:
Microsoft.PowerShell.Utility Module

對包含一組物件的屬性值新增或移除項目。

語法

AddRemoveSet (預設值) 

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

ReplaceSet 

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

Description

該 Update-List cmdlet 會新增、移除或替換物件屬性值中的項目，並回傳更新後的物件。 此 cmdlet 是為包含物件集合的屬性設計的。

新增與移除參數，將個別項目加入或從收藏中移除。 替換參數會替換整個集合。

如果你在指令中沒有指定屬性， Update-List 則會回傳描述更新的雜湊表，而不是更新物件本身。 之後，你可以用這個變更集來更新清單物件。

這個 cmdlet 只有在被更新的屬性支援使用 的 IList 介面 Update-List 時才會生效。 此外，任何 Set 接受更新的 cmdlet 都必須支援 IList 介面。

此 Cmdlet 已在 PowerShell 7 中重新引入。

範例

範例 1：將項目加入房產價值

在這個例子中，我們建立一個類別，代表一副牌組，卡牌以 List 集合物件的形式儲存。 NewDeck（） 方法用於Update-List將一整副牌值加入牌組。

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

Note

Update-List指令長會將更新後的物件輸出到管線。 我們會把輸出 Out-Null 管線輸入，以抑制不想要的顯示。

範例 2：新增與移除集合屬性中的項目

延續範例 1 的程式碼，我們將建立 Cards 類別的實例，以代表一副牌和兩名玩家持有的牌。 我們使用 Update-List cmdlet 來將牌加入玩家手中，並從牌堆中移除牌。

$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♥

輸出顯示牌發給玩家前的牌組狀態。 你可以看到每位玩家從牌堆中拿到五張牌。 最終輸出顯示發牌後牌組的狀態。 Update-List 用來從牌堆中選擇卡牌並加入玩家收藏。 接著，玩家的牌會用 Update-List從牌堆中移除。

範例 3：在單一指令中新增與移除項目

Update-List 允許你在單一指令中使用 新增 與 移除 參數。 在這個例子中，玩家1想棄掉 4♦ 和 6♦ ，並獲得兩張新牌。

# 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♥

範例 4：將變更集套用到清單物件

如果你沒有指定屬性，則 Update-List 會回傳描述更新過程的雜湊表，而不是更新物件本身。 你可以將雜湊表鑄造到 System.PSListModifier 物件，並用該 ApplyTo() 方法將變更集套用到清單上。

$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

參數

-Add

指定要加入集合的屬性值。 輸入這些值，依照它們應該出現在集合中的順序。

參數屬性

類型:

Object[]

預設值:None
支援萬用字元:False
不要顯示:False

參數集

AddRemoveSet
Position:Named
必要:False
來自管線的值:False
來自管線按屬性名稱的值:False
來自剩餘引數的值:False

-InputObject

指定要更新的物件。 你也可以將要更新的物件管道傳送到 Update-List。

參數屬性

類型:PSObject
預設值:None
支援萬用字元:False
不要顯示:False

參數集

(All)
Position:Named
必要:False
來自管線的值:True
來自管線按屬性名稱的值:False
來自剩餘引數的值:False

-Property

指定包含正在更新的集合的屬性。 如果你省略這個參數，會 Update-List 回傳一個代表變更的物件，而不是改變物件本身。

參數屬性

類型:String
預設值:None
支援萬用字元:False
不要顯示:False

參數集

(All)
Position:0
必要:False
來自管線的值:False
來自管線按屬性名稱的值:False
來自剩餘引數的值:False

-Remove

指定要從集合中移除的屬性值。

參數屬性

類型:

Object[]

預設值:None
支援萬用字元:False
不要顯示:False

參數集

AddRemoveSet
Position:Named
必要:False
來自管線的值:False
來自管線按屬性名稱的值:False
來自剩餘引數的值:False

-Replace

指定一個新的收藏。 此參數將原始集合中的所有項目替換為該參數指定的項目。

參數屬性

類型:

Object[]

預設值:None
支援萬用字元:False
不要顯示:False

參數集

ReplaceSet
Position:Named
必要:True
來自管線的值:False
來自管線按屬性名稱的值:False
來自剩餘引數的值:False

CommonParameters

此 cmdlet 支援常見參數：-Debug、-ErrorAction、-ErrorVariable、-InformationAction、-InformationVariable、-OutBuffer、-OutVariable、-PipelineVariable、-ProgressAction、-Verbose、-WarningAction 和 -WarningVariable。 如需詳細資訊，請參閱 about_CommonParameters。

輸入

PSObject

你可以將要更新的物件管道傳送到這個 cmdlet。

輸出

Hashtable

預設情況下，此指令子會回傳一個描述更新的雜湊表。

Object

當你指定 Property 參數時，這個 cmdlet 會回傳更新後的物件。