about_PSItem

Makale
10/04/2023

Kısa açıklama

İşlem hattı nesnesindeki geçerli nesneyi içeren otomatik değişken.

Uzun açıklama

PowerShell, $_geçerli nesneyi işleyen betik bloklarında işlem hattı gibi otomatik değişkenler olarak değişkenini ve diğer adını içerir$PSItem. Bu makalede örneklerde kullanılır $PSItem , ancak $PSItem her örnekte ile $_ değiştirilebilir.

Bu değişkeni, işlem hattındaki her nesne üzerinde eylem gerçekleştiren komutlarda kullanabilirsiniz.

için $PSItembirkaç yaygın kullanım örneği vardır:

cmdlet'in process parametresinin scriptblock'unda ForEach-Object
cmdlet'in FilterScript parametresi için betik bloğunda Where-Object
forEach ve Where iç yöntemlerinde
delay-bind scriptblock parametreleriyle
deyiminin switch koşullu değerlerinde ve ilişkili betik bloklarında
process bir işlevin bloğunda
bir filter tanımda
ValidateScript özniteliğinin betik bloğunda

Bu makalenin geri kalanında bu kullanım örnekleri için kullanım $PSItem örnekleri yer alır.

ForEach-Nesne İşlemi

ForEach-Object cmdlet'i işlem hattındaki nesneler üzerinde çalışacak şekilde tasarlanmıştır ve işlem hattındaki her nesne için İşlem parametresinin betik bloğu bir kez yürütülür.

İşlem parametresinin betik bloğunda kullanabilirsiniz ancak Başlangıç veya Bitiş parametresi betik bloklarında kullanamazsınız$PSItem. Başlangıç veya Bitiş parametresi betik bloklarında başvuruda $PSItem bulunursanız, değerin $null nedeni bu betik bloklarının işlem hattındaki her nesne üzerinde çalışmamadır.

$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

Where-Object cmdlet'i, işlem hattındaki nesneleri filtrelemek için tasarlanmıştır.

İşlem hattındaki her giriş nesnesi için bir kez yürütülen FilterScript parametresinin betik bloğunda kullanabilirsiniz$PSItem.

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

Bu örnekte, FilterScript geçerli nesnenin eşit olup olmadığını denetler, tek değerleri filtreler ve yalnızca 2 özgün listeden döndürür.

ForEach ve Where yöntemleri

Diziler için hem ForEach hem de Where iç yöntemleri giriş parametresi olarak bir betik bloğu alır. Geçerli nesneye erişmek için bu betik bloklarında öğesini $PSItem kullanabilirsiniz.

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

Bu örnekte, ForEach yönteminin betik bloğu geçerli nesnenin büyük harflerini oluşturur. Ardından Where yönteminin betik bloğu yalnızca Bdöndürür.

Gecikme bağlama betiği engelleme parametreleri

Gecikmeli bağlama betik blokları , işlem hattı cmdlet'ini yürütmeden önce parametreleri tanımlamak için kullanmanıza $PSItem olanak sağlar.

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

Switch deyimi betik blokları

Switch deyimlerinde hem eylem betik bloklarında hem de deyim koşulu betik bloklarında kullanabilirsiniz$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

Bu örnekte, deyim koşulu betik bloğu geçerli nesnenin eşit olup olmadığını denetler. Eşitse, ilişkili eylem betik bloğu geçerli nesnenin eşit olduğunu belirten bir ileti oluşturur.

Koşulun eylem betik bloğu, geçerli nesnenin default tek olduğunu belirten bir ileti oluşturur.

İşlev işlemi blokları

bir işlev tanımlarken, blok tanımında process kullanabilirsiniz$PSItem, ancak veya end blok tanımlarında begin kullanamazsınız. veya bloklarında başvuruda $PSItem bulunursanızbegin, değerin $null nedeni bu blokların işlem hattındaki her nesne üzerinde çalışmamadır.end

Blok tanımında kullandığınızda $PSItem , işlev işlem hattında process çağrılırsa değer geçerli nesnedir ve aksi halde $nullolur.

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

1, 2, 3 | Add-One

2
3
4

İpucu

Gelişmiş işlevlerde kullanabilirsiniz $PSItem ancak bunu yapmak için çok az neden vardır. İşlem hattından giriş almayı planlıyorsanız, Parametre özniteliğinin bağımsız değişkenlerinden ValueFromPipeline*biriyle parametreleri tanımlamak en iyisidir.

Gelişmiş işlevler için Parameter özniteliğini ve cmdlet bağlamasını kullanmak, gerekli değerleri almak için uygulamayı geçerli nesneyi işlemeye göre daha açık ve öngörülebilir hale getirir.

Gelişmiş işlevlerde iyi bir kullanım, işlevin $PSItem işlem hattından giriş alan birden çok parametresi olduğunda hata ayıklama veya günlüğe kaydetme için geçerli nesnenin kendisini incelemektir.

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

Bu örnek işlev, bir ileti ve zaman damgası ile bir JSON nesneleri dizisi oluşturur. İşlem hattında çağrıldığında, her giriş için geçerli nesnenin Message özelliğini kullanır. Ayrıca geçerli nesnenin JSON gösterimini ayrıntılı akışa yazar, böylece çıkış günlükleriyle karşılaştırıldığında gerçek girişi görebilirsiniz.

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

Filtre tanımları

Bir filtrenin tanımının deyim listesinde kullanabilirsiniz$PSItem.

Bir tanımda kullandığınızda $PSItem , filtre işlem hattında veya başka bir filter şekilde $nullçağrılırsa değer geçerli nesnedir.

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

1, 2, 3 | Test-IsEven

False
True
False

Bu örnekte, Test-IsEven geçerli nesne çift sayıysa ve $false değilse filtre çıkışını $true verir.

ValidateScript özniteliği betik bloğu

ValidateScript özniteliğinin betik bloğunda kullanabilirsiniz$PSItem. ValidateScript ile kullanıldığında, $PSItem doğrulanan geçerli nesnenin değeridir. Değişken veya parametre değeri bir dizi olduğunda, betik bloğu geçerli nesne olarak dizideki $PSItem her nesne için bir kez çağrılır.

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 : 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.
At line:1 char:24
+ Add-EvenNumber -Number 1, 2
+                        ~~~~
    + CategoryInfo          : InvalidData: (:) [Add-EvenNumber],
   ParameterBindingValidationException
    + FullyQualifiedErrorId : ParameterArgumentValidationError,
   Add-EvenNumber

Bu örnekte ValidateScript özniteliğinin betik bloğu Number parametresine geçirilen her değer için bir kez çalıştırılır ve herhangi bir değer eşit değilse hata döndürür.

Add-EvenNumber işlevi geçerli giriş numaralarını ekler ve toplamı döndürür.