about_PSItem

Cikk
10/04/2023

Rövid leírás

Az automatikus változó, amely az aktuális objektumot tartalmazza a folyamatobjektumban.

Hosszú leírás

A PowerShell automatikus változóként tartalmazza a $PSItem változót és annak aliasát $_az aktuális objektumot feldolgozó szkriptblokkokban, például a folyamatban. Ez a cikk a példákban szerepel $PSItem , de $PSItem minden példában lecserélhető $_ .

Ezt a változót olyan parancsokban használhatja, amelyek műveletet hajtanak végre egy folyamat minden objektumán.

A következő esetekben van néhány gyakori használati eset $PSItem:

parancsmag folyamatparaméterének szkriptblokkjában ForEach-Object
parancsmag FilterScript paraméterének szkriptblokkjában Where-Object
intrinsic methods ForEach és Where
delay-bind scriptblock paraméterekkel
az switch utasítás feltételes értékeiben és a hozzájuk tartozó szkriptblokkokban
függvény process blokkjában
definícióban filter
a ValidateScript attribútum szkriptblokkjában
az operátor helyettesítési operandus-szkriptblokkjában -replace

A cikk további része példákat tartalmaz az ilyen használati esetek használatára $PSItem .

ForEach-Object folyamat

A ForEach-Object parancsmag úgy lett kialakítva, hogy a folyamat összes objektumához végrehajtsa a Folyamat paraméter szkriptblokkját.

A Folyamat paraméter szkriptblokkjában használható$PSItem, de a Begin vagy a End paraméter szkriptblokkjaiban nem. Ha a Begin vagy End paraméter szkriptblokkjaira hivatkozik$PSItem, az érték az, $null hogy ezek a szkriptblokkok nem működnek a folyamat egyes objektumaiban.

$parameters = @{
    Begin   = { Write-Host "PSItem in Begin is: $PSItem" }
    Process = {
        Write-Host "PSItem in Process is: $PSItem"
        $PSItem + 1
    }
    End     = { Write-Host "PSItem in End is: $PSItem" }
}

$result = 1, 2, 3 | ForEach-Object @parameters

Write-Host "Result is: $result"

PSItem in Begin is:
PSItem in Process is: 1
PSItem in Process is: 2
PSItem in Process is: 3
PSItem in End is:
Result is: 2 3 4

Where-Object FilterScript

A Where-Object parancsmag célja a folyamat objektumainak szűrése.

Használhatja $PSItem a FilterScript paraméter szkriptblokkjában, amely a folyamat minden bemeneti objektumához egyszer hajt végre.

1, 2, 3 | Where-Object -FilterScript { ($PSItem % 2) -eq 0 }

Ebben a példában a FilterScript ellenőrzi, hogy az aktuális objektum páros-e, kiszűri a páratlan értékeket, és csak 2 az eredeti listából ad vissza.

ForEach és Where metódusok

A tömbök ForEach és Where belső metódusai egyaránt szkriptblokkot használnak bemeneti paraméterként. A $PSItem szkriptblokkok használatával elérheti az aktuális objektumot.

@('a', 'b', 'c').ForEach({ $PSItem.ToUpper() }).Where({ $PSItem -ceq 'B' })

Ebben a példában a ForEach metódus szkriptblokkja nagybetűssé emeli az aktuális objektumot. Ezután a Where metódus szkriptblokkja csak Ba függvényt adja vissza.

Delay-bind scriptblock paraméterek

A késleltetési kötés szkriptblokkjai lehetővé teszik $PSItem a folyamatalapú parancsmag paramétereinek definiálását a végrehajtás előtt.

dir config.log | Rename-Item -NewName { "old_$($_.Name)" }

Utasításszkriptblokkok váltása

A kapcsolóutasításokban műveletszkriptblokkokban és utasításállapot-szkriptblokkokban is használható $PSItem .

$numbers = 1, 2, 3

switch ($numbers) {
    { ($PSItem % 2) -eq 0 } { "$PSItem is even" }
    default { "$PSItem is odd" }
}

1 is odd
2 is even
3 is odd

Ebben a példában az utasításfeltétel szkriptblokkja ellenőrzi, hogy az aktuális objektum páros-e. Ha ez páros, a társított műveleti szkriptblokk egy üzenetet ad ki, amely azt jelzi, hogy az aktuális objektum egyenlő.

A feltétel műveletszkriptblokkja default egy üzenetet ad ki, amely jelzi, hogy az aktuális objektum páratlan.

Függvényfolyamat-blokkok

Ha definiál egy függvényt, használhatja $PSItem a process blokkdefiníciót, de nem a endbegin blokkdefiníciókban. Ha a endbegin blokkokra hivatkozik$PSItem, az érték az, $null hogy ezek a blokkok nem működnek a folyamat egyes objektumaiban.

Ha a blokkdefinícióban használja$PSItem, az érték az aktuális objektum, ha a függvényt meghívják a folyamatban, és egyébként$null.process

function Add-One {
    process { $PSItem + 1 }
}

1, 2, 3 | Add-One

2
3
4

Tipp.

Bár speciális függvényekben is használható$PSItem, erre kevés oka van. Ha bemenetet szeretne kapni a folyamatból, a legjobb, ha paramétereket határoz meg a ValueFromPipeline*Paraméter attribútum egyik argumentumával.

A paraméterattribútum és a parancsmag-kötés speciális függvényekhez való használata explicitebbé és kiszámíthatóbbá teszi a megvalósítást, mint az aktuális objektum feldolgozása a szükséges értékek lekéréséhez.

A speciális függvények egyik jó funkciója $PSItem , ha az aktuális objektumot vizsgálja meg hibakeresés vagy naplózás céljából, ha a függvény több paramétert is használ, amelyek bemenetet vesznek fel a folyamatból.

function Write-JsonLog {
    [CmdletBinding()]
    param(
        [parameter(ValueFromPipelineByPropertyName)]
        [string]$Message
    )
    begin {
        $entries = @()
    }
    process {
        $entries += [pscustomobject]@{
            Message   = $Message
            TimeStamp = [datetime]::Now
        }

        if ($PSItem) {
            $props  = $PSItem | ConvertTo-Json
            $number = $entries.Length
            Write-Verbose "Input object $number is:`n$props"
        }
    }
    end {
        ConvertTo-Json -InputObject $entries
    }
}

Ez a példafüggvény JSON-objektumokból álló tömböt ad ki üzenettel és időbélyeggel. Amikor egy folyamat meghívja, minden egyes bejegyzéshez az aktuális objektum Üzenet tulajdonságát használja. Az aktuális objektum JSON-ábrázolását is a részletes adatfolyamba írja, így a kimeneti naplókhoz képest láthatja a tényleges bemenetet.

$Items = @(
    [pscustomobject]@{
        Name    = 'First Item'
        Message = 'A simple note'
    }
    [pscustomobject]@{
        Name    = 'Item with extra properties'
        Message = 'Missing message, has info instead'
        Info    = 'Some metadata'
        Source  = 'Where this came from'
    }
    [pscustomobject]@{
        Name    = 'Last Item'
        Message = 'This also gets logged'
    }
)

$Items | Write-JsonLog -Verbose

VERBOSE: Input object 1 is:
{
    "Name":  "First Item",
    "Message":  "A simple note"
}
VERBOSE: Input object 2 is:
{
    "Name":  "Item with extra properties",
    "Message":  "Missing message, has info instead",
    "Info":  "Some metadata",
    "Source":  "Where this came from"
}
VERBOSE: Input object 3 is:
{
    "Name":  "Last Item",
    "Message":  "This also gets logged"
}
[
    {
        "Message":  "A simple note",
        "TimeStamp":  "\/Date(1670344068257)\/"
    },
    {
        "Message":  "Missing message, has info instead",
        "TimeStamp":  "\/Date(1670344068259)\/"
    },
    {
        "Message":  "This also gets logged",
        "TimeStamp":  "\/Date(1670344068261)\/"
    }
]

Definíciók szűrése

A szűrő definíciójának utasításlistájában használható$PSItem.

Definíció $PSItem használata filter esetén az érték az aktuális objektum, ha a szűrőt a folyamat meghívja, és ellenkező esetben.$null

filter Test-IsEven { ($PSItem % 2) -eq 0 }

1, 2, 3 | Test-IsEven

False
True
False

Ebben a példában a Test-IsEven szűrő akkor jelenik $true meg, ha az aktuális objektum páros szám, és $false ha nem.

A ValidateScript attribútum szkriptblokkja

A ValidateScript attribútum szkriptblokkjában is használható$PSItem. A ValidateScript$PSItem használata esetén az érvényesített aktuális objektum értéke. Ha a változó vagy paraméter értéke tömb, a szkriptblokkot a tömb $PSItem minden egyes objektumához meghívja az aktuális objektumként.

function Add-EvenNumber {
    param(
        [ValidateScript({ 0 -eq ($PSItem % 2) })]
        [int[]]$Number
    )

    begin {
        [int]$total = 0
    }

    process {
        foreach ($n in $Number) {
            $total += $n
        }
    }

    end {
        $total
    }
}

Add-EvenNumber -Number 2, 4, 6

Add-EvenNumber -Number 1, 2

12

Add-EvenNumber:
Line |
  24 |  Add-EvenNumber -Number 1, 2
     |                         ~~~~
     | Cannot validate argument on parameter 'Number'. The
" 0 -eq ($PSItem % 2) " validation script for the argument
with value "1" did not return a result of True. Determine
why the validation script failed, and then try the command
again.

Ebben a példában a ValidateScript attribútum szkriptblokkja egyszer fut a Szám paraméternek átadott összes értéknél, és hibát ad vissza, ha egy érték nem is egyenletes.

A Add-EvenNumber függvény hozzáadja az érvényes bemeneti számokat, és visszaadja a végösszeget.

A -replace operátor helyettesítési szkriptblokkja

A PowerShell 6-tól kezdve használhatja $PSItem a csereműveleti operátor meghívását és egy helyettesítési szkriptblokk definiálását. Ha így tesz, az érték $PSItem az aktuális egyezés értéke.

$datePattern = '\d{4}-\d{2}-\d{2}'
'Today is 1999-12-31' -replace $datePattern, { [datetime]$PSItem.Value }

Today is 12/31/1999 00:00:00

Ebben a példában a helyettesítési szkriptblokk az eredeti dátumsztringet az aktuális kultúra alapértelmezett formátumára cseréli úgy, hogy az értéket dátum/idő értékre irányítja.