about_PSItem
Descripción breve
Variable automática que contiene el objeto actual en el objeto de canalización.
Descripción larga
PowerShell incluye la $PSItem variable y su alias, , $_como variables automáticas en los bloques de script que procesan el objeto actual, como en la canalización. En este artículo se usa $PSItem en los ejemplos, pero $PSItem se puede reemplazar por $_ en cada ejemplo.
Puede usar esta variable en comandos que realizan una acción en cada objeto de una canalización.
Hay algunos casos de uso comunes para $PSItem:
- en el scriptblock para el parámetro Process del
ForEach-Objectcmdlet - en el scriptblock para el parámetro FilterScript del
Where-Objectcmdlet - en los métodos intrínsecos ForEach y Where
- con parámetros de scriptblock de enlace retrasado
- en los valores condicionales de una
switchinstrucción y los bloques de script asociados - en el
processbloque de una función - en una
filterdefinición - en el scriptblock del atributo ValidateScript
El resto de este artículo incluye ejemplos de uso $PSItem para estos casos de uso.
Proceso de foreach-object
El cmdlet ForEach-Object está diseñado para operar en objetos de la canalización, ejecutando el bloque de scripts del parámetro Process una vez para cada objeto de la canalización.
Puede usar $PSItem en el scriptblock del parámetro Process , pero no en los bloques de script de parámetro Begin o End . Si hace referencia $PSItem a los scriptblocks del parámetro Begin o End , el valor se debe $null a que esos bloques de script no funcionan en cada objeto de la canalización.
$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
El cmdlet Where-Object está diseñado para filtrar objetos en la canalización.
Puede usar $PSItem en el scriptblock del parámetro FilterScript , que se ejecuta una vez para cada objeto de entrada de la canalización.
1, 2, 3 | Where-Object -FilterScript { ($PSItem % 2) -eq 0 }
2
En este ejemplo, FilterScript comprueba si el objeto actual es par, filtrando los valores impares y devuelve solo 2 de la lista original.
Métodos ForEach y Where
Los métodos intrínsecos ForEach y Where para las matrices toman un scriptblock como parámetro de entrada. Puede usar en $PSItem esos bloques de script para tener acceso al objeto actual.
@('a', 'b', 'c').ForEach({ $PSItem.ToUpper() }).Where({ $PSItem -ceq 'B' })
B
En este ejemplo, el bloque de scripts del método ForEach en mayúsculas el objeto actual. A continuación, el scriptblock del método Where devuelve solo B.
Parámetros de scriptblock de enlace retrasado
Los bloques de script de enlace retrasado permiten usar $PSItem para definir parámetros para un cmdlet canalización antes de ejecutarlo.
dir config.log | Rename-Item -NewName { "old_$($_.Name)" }
Bloqueos de script de instrucción switch
En las instrucciones switch, puede usar $PSItem en los bloques de scriptblocks de acción y en los scriptblocks de condición de instrucción.
$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
En este ejemplo, el scriptblock de condición de instrucción comprueba si el objeto actual es par. Si es incluso, el scriptblock de acción asociado genera un mensaje que indica que el objeto actual es incluso.
El bloque de script de acción de la default condición genera un mensaje que indica que el objeto actual es impar.
Bloques de proceso de función
Al definir una función, puede usar $PSItem en la definición de process bloque, pero no en las begin definiciones de bloque o end . Si hace referencia $PSItem a en los begin bloques o end , el valor se debe $null a que esos bloques no operan en cada objeto de la canalización.
Cuando se usa $PSItem en la definición de process bloque, el valor es el objeto actual si se llama a la función en la canalización y, de lo contrario $null, .
function Add-One {
process { $PSItem + 1 }
}
1, 2, 3 | Add-One
2
3
4
Sugerencia
Aunque puede usar $PSItem en funciones avanzadas, hay poca razón para hacerlo. Si piensa recibir la entrada de la canalización, es mejor definir parámetros con uno de los ValueFromPipeline* argumentos del atributo Parameter .
El uso del atributo Parameter y el enlace de cmdlets para funciones avanzadas hace que la implementación sea más explícita y predecible que procesar el objeto actual para obtener los valores necesarios.
Un buen uso de $PSItem en funciones avanzadas es inspeccionar el propio objeto actual para depurar o registrar cuando la función tiene varios parámetros que toman la entrada de la canalización.
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
}
}
Esta función de ejemplo genera una matriz de objetos JSON con un mensaje y una marca de tiempo. Cuando se llama en una canalización, usa la propiedad Message del objeto actual para cada entrada. También escribe la representación JSON del propio objeto actual en el flujo detallado, por lo que puede ver la entrada real en comparación con los registros de salida.
$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)\/"
}
]
Definiciones de filtro
Puede usar $PSItem en la lista de instrucciones de la definición de un filtro.
Cuando se usa $PSItem en una filter definición, el valor es el objeto actual si se llama al filtro en la canalización y, de lo contrario $null, .
filter Test-IsEven { ($PSItem % 2) -eq 0 }
1, 2, 3 | Test-IsEven
False
True
False
En este ejemplo, el Test-IsEven filtro genera $true si el objeto actual es un número par y $false si no lo es.
El bloque de scripts del atributo ValidateScript
Puede usar $PSItem en el scriptblock de un atributo ValidateScript .
Cuando se usa con ValidateScript, $PSItem es el valor del objeto actual que se va a validar. Cuando el valor de la variable o del parámetro es una matriz, se llama a scriptblock una vez para cada objeto de la matriz con $PSItem como objeto actual.
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
En este ejemplo, el scriptblock para el atributo ValidateScript se ejecuta una vez para cada valor pasado al parámetro Number , devolviendo un error si algún valor no es ni siquiera.
La Add-EvenNumber función agrega los números de entrada válidos y devuelve el total.
