Číst v angličtině

Sdílet prostřednictvím

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 bloku skriptu pro parametr Process cmdletu ForEach-Object
  • V skriptblocku pro parametr FilterScript příkazu Where-Object
  • Vnitřní metody ForEach a Where
  • s parametry skriptu s vazbou zpoždění
  • V podmíněných hodnotách příkazu switch a přidružených skriptových blokech
  • V process bloku funkce
  • V definici filter
  • V bloku skriptu atributu ValidateScript
  • V skriptovém bloku příkazu catch
  • V nahrazovacím operandovém bloku 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.

PowerShell 
$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"
Output 
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.

PowerShell 
1, 2, 3 | Where-Object -FilterScript { ($PSItem % 2) -eq 0 }
Output 
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.

PowerShell 
@('a', 'b', 'c').ForEach({ $PSItem.ToUpper() }).Where({ $PSItem -ceq 'B' })
Output 
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.

PowerShell 
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.

PowerShell 
$numbers = 1, 2, 3

switch ($numbers) {
    { ($PSItem % 2) -eq 0 } { "$PSItem is even" }
    default { "$PSItem is odd" }
}
Output 
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.

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

1, 2, 3 | Add-One
Output 
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.

PowerShell 
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.

PowerShell 
$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
Output 
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.

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

1, 2, 3 | Test-IsEven
Output 
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 $PSItem můžete použít. 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 .

PowerShell 
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
Output 
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 příkazu catch

V rámci bloku catch lze k aktuální chybě přistupovat pomocí $PSItem. Objekt je typu ErrorRecord.

PowerShell 
try { NonsenseString }
catch {
    Write-Host "An error occurred:"
    Write-Host $_
}

Spuštění tohoto skriptu vrátí následující výsledek:

Output 
An Error occurred:
The term 'NonsenseString' is not recognized as the name of a cmdlet, function,
script file, or operable program. Check the spelling of the name, or if a path
was included, verify that the path is correct and try again.

Další příklady najdete v části Přístup k informacím o výjimce v about_Try_Catch_Finally.

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.

PowerShell 
$datePattern = '\d{4}-\d{2}-\d{2}'
'Today is 1999-12-31' -replace $datePattern, { [datetime]$PSItem.Value }
Output 
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é