about_PSItem

  • Článek

Krátký popis

Automatická proměnná, která obsahuje aktuální objekt v objektu kanálu.

Dlouhý popis

PowerShell obsahuje proměnnou $PSItem a její alias, $_jako automatické proměnné v blokech skriptu, které zpracovávají aktuální objekt, například v kanálu. Tento článek se používá $PSItem v příkladech, ale $PSItem může být nahrazen $_ v každém příkladu.

Tuto proměnnou můžete použít v příkazech, které provádějí akci u každého objektu v kanálu.

Existuje několik běžných případů použití:$PSItem

  • v scriptblock pro process parametr rutiny ForEach-Object
  • ve skriptublock pro parametr FilterScript rutiny Where-Object
  • vnitřní metody ForEach a Where
  • s parametry skriptu s vazbou zpoždění
  • switch v podmíněných hodnotách příkazu a přidružených skriptových blokech
  • process v bloku funkce
  • v definici filter
  • v scriptblock atributu ValidateScript
  • v náhradním operandovém skriptu operátoru -replace

Zbytek tohoto článku obsahuje příklady použití $PSItem pro tyto případy použití.

Proces forEach-Object

Rutina ForEach-Object je navržená tak, aby fungovala s objekty v kanálu a jednou pro každý objekt v kanálu spouštěla skriptblock parametru Process .

V bloku skriptu parametru Process můžete použít $PSItem, ale ne ve skriptech parametrů Begin nebo End. Pokud odkazujete $PSItem na skripty begin nebo end parametru, hodnota je $null , že tyto skripty nefungují u každého objektu v kanálu.

$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

Rutina Where-Object je navržená k filtrování objektů v kanálu.

Můžete použít $PSItem ve skriptublock parametru FilterScript , který se spustí jednou pro každý vstupní objekt v kanálu.

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

2

V tomto příkladu FiltrScript zkontroluje, jestli je aktuální objekt sudý, odfiltruje všechny liché hodnoty a vrátí pouze 2 z původního seznamu.

Metody ForEach a Where

Vnitřní metody ForEach a Where pro pole přebírají skriptblock jako vstupní parametr. Pomocí těchto skriptů můžete $PSItem získat přístup k aktuálnímu objektu.

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

B

V tomto příkladu skriptblock metody ForEach velká písmena aktuální objekt. Pak scriptblock metody Where vrátí pouze B.

Parametry bloku skriptu s vazbou zpoždění

Bloky skriptů s vazbou zpoždění umožňují před $PSItem spuštěním definovat parametry pro rutinu kanálu.

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

Switch – bloky skriptů příkazů

V příkazech switch můžete použít $PSItem skripty akcí i skripty podmínky příkazu.

$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

V tomto příkladu skriptblock podmínky příkazu zkontroluje, zda je aktuální objekt sudý. Pokud je to sudé, přidružený skript akce scriptblock zobrazí zprávu označující, že aktuální objekt je sudý.

Skript akce pro podmínku default vypíše zprávu označující, že aktuální objekt je lichý.

Bloky procesu funkce

Když definujete funkci, můžete ji použít $PSItem v process definici bloku, ale ne v beginend definicích bloků. Pokud odkazujete $PSItem na objekty begin nebo end bloky, je $null tato hodnota způsobená tím, že tyto bloky nepracují s každým objektem v kanálu.

Pokud použijete $PSItem v process definici bloku, hodnota je hodnota je aktuální objekt, pokud je funkce volána v kanálu a jinak $null.

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

1, 2, 3 | Add-One

2
3
4

Tip

I když můžete použít $PSItem v pokročilých funkcích, existuje malý důvod k tomu. Pokud máte v úmyslu přijímat vstupy z kanálu, je nejlepší definovat parametry pomocí jednoho z ValueFromPipeline* argumentů pro atribut Parameter .

Použití atributu Parameter a vazby rutin pro pokročilé funkce umožňuje implementaci explicitnější a předvídatelnější než zpracování aktuálního objektu k získání požadovaných hodnot.

Jedním z vhodných použití v pokročilých funkcích $PSItem je zkontrolovat aktuální objekt pro ladění nebo protokolování, pokud má funkce více parametrů, které přebírají vstup z kanálu.

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

Tato ukázková funkce vypíše pole objektů JSON se zprávou a časovým razítkem. Při zavolání v kanálu používá vlastnost Message aktuálního objektu pro každou položku. Zapisuje také reprezentaci JSON aktuálního objektu do podrobného datového proudu, takže můžete vidět skutečný vstup v porovnání s výstupními protokoly.

$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)\/"
    }
]

Definice filtru

Můžete použít $PSItem v seznamu příkazů definice filtru.

Při použití $PSItem v filter definici je hodnota aktuální objekt, pokud je filtr volána v kanálu a jinak $null.

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

1, 2, 3 | Test-IsEven

False
True
False

V tomto příkladu Test-IsEven filtruje $true výstup, pokud je aktuální objekt sudým číslem a $false pokud ne.

Blok skriptu atributu ValidateScript

V bloku skriptu atributu ValidateScript můžete použít$PSItem. Při použití s ValidateScriptem je hodnota aktuálního objektu, $PSItem který se ověřuje. Pokud je proměnná nebo hodnota parametru pole, je skriptblock volána jednou pro každý objekt v poli s aktuálním objektem $PSItem .

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.

V tomto příkladu se skriptblock atributu ValidateScript spustí jednou pro každou hodnotu předanou parametru Number a vrátí chybu, pokud žádná hodnota ani není.

Funkce Add-EvenNumber sečte platná vstupní čísla a vrátí součet.

Blok skriptu nahrazení operátoru -replace

Počínaje PowerShellem 6 můžete použít $PSItem při volání operátoru nahrazení a definování náhradního bloku skriptu. Když to uděláte, hodnota $PSItem je hodnota aktuální shody.

$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

V tomto příkladu nahradí blok náhradního skriptu původní řetězec kalendářního data výchozím formátem pro aktuální jazykovou verzi přetypováním hodnoty na datetime.

Viz také