about_Automatic_Variables

Artículo
07/12/2024

Descripción breve

Describe las variables que almacenan información de estado para y se crean y mantienen mediante PowerShell.

Conceptualmente, la mayoría de estas variables se consideran de solo lectura. Aunque se puedan escribir en, por motivos de compatibilidad con versiones anteriores no deben escribirse.

Esta es una lista de las variables automáticas en PowerShell:

$$
$?
$^
$_
$args
$ConsoleFileName
$Error
$Event
$EventArgs
$EventSubscriber
$ExecutionContext
$false
$foreach
$HOME
$Host
$input
$LASTEXITCODE
$Matches
$MyInvocation
$NestedPromptLevel
$null
$PID
$PROFILE
$PSBoundParameters
$PSCmdlet
$PSCommandPath
$PSCulture
$PSDebugContext
$PSEdition
$PSHOME
$PSItem
$PSScriptRoot
$PSSenderInfo
$PSUICulture
$PSVersionTable
$PWD
$Sender
$ShellId
$StackTrace
$switch
$this
$true

Descripción larga

$$

Contiene el último token de la última línea recibida por la sesión.

$?

Contiene el estado de ejecución del último comando. Contiene True si el último comando se realizó correctamente y False si se produjo un error. Los errores de análisis no dan lugar a la ejecución, por lo que no afectan al valor de $?.

Para cmdlets y funciones avanzadas que se ejecutan en varias fases de una canalización, por ejemplo, en process bloques y end , llamando a this.WriteError() o $PSCmdlet.WriteError() respectivamente en cualquier punto establece en $? False, como sí this.ThrowTerminatingError() y $PSCmdlet.ThrowTerminatingError().

El Write-Error cmdlet siempre establece $? en False inmediatamente después de ejecutarlo, pero no se establecerá en $? False para una función que lo llame:

function Test-WriteError
{
    Write-Error "Bad"
    "The `$? variable is: $?"
}

Test-WriteError
"Now the `$? variable is: $?"

Test-WriteError : Bad
At line:7 char:1
+ Test-WriteError
+ ~~~~~~~~~~~~~~~
    + CategoryInfo          : NotSpecified: (:) [Write-Error], WriteErrorException
    + FullyQualifiedErrorId : Microsoft.PowerShell.Commands.WriteErrorException,Test-WriteError

The $? variable is: False
Now the $? variable is: True

Para este último propósito, $PSCmdlet.WriteError() debe usarse en su lugar.

En el caso de los comandos nativos (ejecutables), $? se establece en True cuando $LASTEXITCODE es 0 y se establece en False cuando $LASTEXITCODE es cualquier otro valor.

Nota:

Hasta PowerShell 7, ajustar una instrucción entre paréntesis (...), sintaxis $(...)de subexpresión o una expresión @(...) de matriz siempre se restablece $? a True. Por ejemplo, (Write-Error) se muestra $? como True. Este comportamiento ha cambiado en PowerShell 7, de modo que $? siempre refleje el éxito real de la última ejecución del comando en estas expresiones.

$^

Contiene el primer token de la última línea recibida por la sesión.

$_

Igual que $PSItem. Contiene el objeto actual en el objeto de canalización. Puede usar esta variable en comandos que realizan una acción en cada objeto de una canalización.

Para obtener más información, consulte about_PSItem.

$args

Contiene una matriz de valores para parámetros no declarados que se pasan a una función, un script o un bloque de scripts. Al crear una función, puede declarar los parámetros con la param palabra clave o agregando una lista separada por comas de parámetros entre paréntesis después del nombre de la función.

En una acción de evento, la $args variable contiene objetos que representan los argumentos de evento del evento que se está procesando. Esta variable solo se rellena dentro del Action bloque de un comando de registro de eventos. El valor de esta variable también se puede encontrar en la propiedad SourceArgs del PSEventArgs objeto que Get-Event devuelve.

$ConsoleFileName

Contiene la ruta de acceso del archivo de consola (.psc1) que se usó más recientemente en la sesión. Esta variable se rellena al iniciar PowerShell con el parámetro PSConsoleFile o cuando se usa el Export-Console cmdlet para exportar nombres de complemento a un archivo de consola.

Cuando se usa el Export-Console cmdlet sin parámetros, se actualiza automáticamente el archivo de consola que se usó más recientemente en la sesión. Puede usar esta variable automática para determinar el archivo que se va a actualizar.

Error$

Contiene una matriz de objetos de error que representan los errores más recientes. El error más reciente es el primer objeto de error de la matriz $Error[0].

Para evitar que se agregue un error a la $Error matriz, use el parámetro común ErrorAction con un valor de Ignore. Para obtener más información, consulta about_CommonParameters.

$Event

Contiene un PSEventArgs objeto que representa el evento que se está procesando. Esta variable solo se rellena dentro del Action bloque de un comando de registro de eventos, como Register-ObjectEvent. El valor de esta variable es el mismo objeto que devuelve el Get-Event cmdlet. Puede usar las propiedades de la Event variable, como $Event.TimeGenerated, en un Action bloque de script.

$EventArgs

Contiene un objeto que representa el primer argumento de evento que deriva de EventArgs del evento que se está procesando. Esta variable solo se rellena dentro del Action bloque de un comando de registro de eventos. El valor de esta variable también se puede encontrar en la propiedad SourceEventArgs del PSEventArgs objeto que Get-Event devuelve.

$EventSubscriber

Contiene un PSEventSubscriber objeto que representa el suscriptor de eventos del evento que se está procesando. Esta variable solo se rellena dentro del Action bloque de un comando de registro de eventos. El valor de esta variable es el mismo objeto que devuelve el Get-EventSubscriber cmdlet.

$ExecutionContext

Contiene un objeto EngineIntrinsics que representa el contexto de ejecución del host de PowerShell. Puede usar esta variable para buscar los objetos de ejecución que están disponibles para los cmdlets.

$false

Contiene False. Puede usar esta variable para representar False en comandos y scripts en lugar de usar la cadena "false". La cadena se puede interpretar como True si se convierte en una cadena no vacía o en un entero distinto de cero.

$foreach

Contiene el enumerador (no los valores resultantes) de un bucle ForEach . La $ForEach variable solo existe mientras se ejecuta el ForEach bucle; se elimina una vez completado el bucle.

Los enumeradores contienen propiedades y métodos que puede usar para recuperar valores de bucle y cambiar la iteración del bucle actual. Para obtener más información, consulte Uso de enumeradores.

$HOME

Contiene la ruta de acceso completa del directorio principal del usuario. Esta variable usa el valor de la "$env:USERPROFILE" variable de entorno de Windows, normalmente C:\Users\<UserName>.

Importante

Windows puede redirigir la ubicación del perfil del usuario. Esto significa que puede que no tenga el mismo valor que $HOME "$env:HOMEDRIVE$env:HOMEPATH".

$Host

Contiene un objeto que representa la aplicación host actual para PowerShell. Puede usar esta variable para representar el host actual en comandos o para mostrar o cambiar las propiedades del host, como $Host.version o $Host.CurrentCulture, o $Host.UI.RawUI.BackGroundColor = "Red".

$input

Contiene un enumerador que enumera todas las entradas que se pasan a una función. La $input variable solo está disponible para funciones, bloques de script (que son funciones sin nombre) y archivos de script (que se guardan bloques de script).

En una función sin un beginbloque , processo end , la $input variable enumera la colección de todas las entradas para la función.
En el begin bloque , la $input variable no contiene datos.
En el process bloque , la $input variable contiene el objeto actual de la canalización.
En el end bloque , la $input variable enumera la colección de todas las entradas de la función.

Nota:

No se puede usar la $input variable dentro del process bloque y del end bloque en la misma función o bloque de script.

Como $input es un enumerador, el acceso a cualquiera de sus propiedades hace $input que ya no esté disponible. Puede almacenar $input en otra variable para reutilizar las $input propiedades.

La $input variable también está disponible para el comando especificado por el -Command parámetro de cuando se invoca desde la línea de powershell.exe comandos. En el ejemplo siguiente se ejecuta desde el shell de comandos de Windows.

echo Hello | powershell -Command """$input World!"""

$LASTEXITCODE

Contiene el código de salida del último programa nativo o script de PowerShell que se ejecutó.

En el caso de los scripts de PowerShell, el valor de depende de $LASTEXITCODE cómo se llamó al script y de si se usó la exit palabra clave :

Cuando un script usa la exit palabra clave :

$LASTEXITCODE se establece en el valor especificado por la exit palabra clave . Para obtener más información, consulte about_Language_Keywords.
Cuando se llama directamente a un script, como ./Test.ps1, o con el operador de llamada (&) como & ./Test.ps1:

El valor de $LASTEXITCODE no se cambia a menos que:
- El script llama a otro script que usa la palabra clave .exit
- El script llama a un comando nativo.
- El script usa la exit palabra clave
Cuando se llama a un script con powershell.exe mediante el parámetro File , $LASTEXITCODE se establece en:
- 1 si el script finalizó debido a una excepción
- Valor especificado por la exit palabra clave , si se usa en el script.
- 0 si el script se completó correctamente
Cuando se llama a un script con powershell.exe mediante el parámetro Command , $LASTEXITCODE se establece en:
- 1 si el script finalizó debido a una excepción o si el resultado del último comando establecido $? en $false
- 0si el script se completó correctamente y el resultado del último comando establecido en $?$true

Para obtener más información sobre los parámetros File y Command , consulte about_PowerShell_exe.

$Matches

La $Matches variable funciona con los -match operadores y -notmatch . Cuando se envía una entrada escalar al -match operador o -notmatch y se detecta una coincidencia, devuelven un valor booleano y rellenan la $Matches variable automática con una tabla hash de los valores de cadena coincidentes. La $Matches tabla hash también se puede rellenar con capturas cuando se usan expresiones regulares con el -match operador .

Para obtener más información sobre el -match operador, consulte about_Comparison_Operators. Para obtener más información sobre las expresiones regulares, consulte about_Regular_Expressions.

La $Matches variable también funciona en una switch instrucción con el -Regex parámetro . Se rellena de la misma manera que los -match operadores y -notmatch . Para obtener más información sobre la switch instrucción , consulte about_Switch.

Nota:

Cuando $Matches se rellena en una sesión, conserva el valor coincidente hasta que se sobrescribe mediante otra coincidencia. Si -match se usa de nuevo y no se encuentra ninguna coincidencia, no se restablece $Matches a $null. El valor coincidente anteriormente se mantiene en $Matches hasta que se encuentra otra coincidencia.

$MyInvocation

Contiene información sobre el comando actual, como el nombre, los parámetros, los valores de parámetro y la información sobre cómo se inició, llamó o invocó el comando, como el nombre del script que llamó al comando actual.

$MyInvocation solo se rellena para scripts, funciones y bloques de scripts. Puede usar la información del objeto System.Management.Automation.InvocationInfo que $MyInvocation devuelve en el script actual, como el nombre de una función ($MyInvocation.MyCommand.Name) para identificar el comando actual. Esto resulta útil para buscar el nombre del script actual.

A partir de PowerShell 3.0, MyInvocation tiene las siguientes propiedades nuevas.

PSScriptRoot : contiene la ruta de acceso completa al script que invocó el comando actual. El valor de esta propiedad se rellena solo cuando el autor de la llamada es un script.
PSCommandPath : contiene la ruta de acceso completa y el nombre de archivo del script que invocó el comando actual. El valor de esta propiedad se rellena solo cuando el autor de la llamada es un script.

A diferencia de las $PSScriptRoot variables y $PSCommandPath automáticas, las propiedades PSScriptRoot y PSCommandPath de la $MyInvocation variable automática contienen información sobre el invocador o el script de llamada, no el script actual.

$NestedPromptLevel

Contiene el nivel de solicitud actual. Un valor de 0 indica el nivel de solicitud original. El valor se incrementa cuando se escribe un nivel anidado y se disminuye al salir de él.

Por ejemplo, PowerShell presenta un símbolo del sistema anidado cuando se usa el $Host.EnterNestedPrompt método . PowerShell también presenta un símbolo del sistema anidado cuando se alcanza un punto de interrupción en el depurador de PowerShell.

Al escribir un símbolo del sistema anidado, PowerShell pausa el comando actual, guarda el contexto de ejecución e incrementa el valor de la $NestedPromptLevel variable. Para crear símbolos del sistema anidados adicionales (hasta 128 niveles) o para volver al símbolo del sistema original, complete el comando o escriba exit.

La $NestedPromptLevel variable le ayuda a realizar un seguimiento del nivel de solicitud. Puede crear un símbolo del sistema de PowerShell alternativo que incluya este valor para que siempre esté visible.

$null

$null es una variable automática que contiene un valor nulo o vacío. Puede usar esta variable para representar un valor no definido o ausente en comandos y scripts.

PowerShell trata $null como un objeto con un valor o un marcador de posición, por lo que puede usar $null para representar un valor vacío en una colección de valores.

Por ejemplo, cuando $null se incluye en una colección, se cuenta como uno de los objetos .

$a = "one", $null, "three"
$a.count

Si canaliza la $null variable al ForEach-Object cmdlet , genera un valor para $null, igual que para los demás objetos.

"one", $null, "three" | ForEach-Object { "Hello " + $_}

Hello one
Hello
Hello three

Como resultado, no se puede usar $null para indicar ningún valor de parámetro. Un valor de parámetro de $null invalida el valor de parámetro predeterminado.

Sin embargo, dado que PowerShell trata la $null variable como marcador de posición, puede usarla en scripts como el siguiente, que no funcionaría si $null se ignoraran.

$calendar = @($null, $null, "Meeting", $null, $null, "Team Lunch", $null)
$days = "Sunday","Monday","Tuesday","Wednesday","Thursday",
        "Friday","Saturday"
$currentDay = 0
foreach($day in $calendar)
{
    if($day -ne $null)
    {
        "Appointment on $($days[$currentDay]): $day"
    }

    $currentDay++
}

Appointment on Tuesday: Meeting
Appointment on Friday: Team lunch

$PID

Contiene el identificador de proceso (PID) del proceso que hospeda la sesión actual de PowerShell.

$PROFILE

Contiene la ruta de acceso completa del perfil de PowerShell para el usuario actual y la aplicación host actual. Puede usar esta variable para representar el perfil en comandos. Por ejemplo, puede usarlo en un comando para determinar si se ha creado un perfil:

Test-Path $PROFILE

O bien, puede usarlo en un comando para crear un perfil:

New-Item -ItemType file -Path $PROFILE -Force

Puede usarlo en un comando para abrir el perfil en notepad.exe:

notepad.exe $PROFILE

$PSBoundParameters

Contiene un diccionario de los parámetros que se pasan a un script o función y sus valores actuales. Esta variable tiene un valor solo en un ámbito en el que se declaran los parámetros, como un script o una función. Puede usarlo para mostrar o cambiar los valores actuales de los parámetros o para pasar valores de parámetro a otro script o función.

En este ejemplo, la función Test2 pasa a $PSBoundParameters la función Test1 . $PSBoundParameters Se muestran en el formato clave y valor.

function Test1 {
   param($a, $b)

   # Display the parameters in dictionary format.
   $PSBoundParameters
}

function Test2 {
   param($a, $b)

   # Run the Test1 function with $a and $b.
   Test1 @PSBoundParameters
}

Test2 -a Power -b Shell

Key   Value
---   -----
a     Power
b     Shell

$PSCmdlet

Contiene un objeto que representa el cmdlet o la función avanzada que se está ejecutando.

Puede usar las propiedades y los métodos del objeto en el código de cmdlet o función para responder a las condiciones de uso. Por ejemplo, la propiedad ParameterSetName contiene el nombre del conjunto de parámetros que se usa y el método ShouldProcess agrega los parámetros WhatIf y Confirm al cmdlet dinámicamente.

Para obtener más información sobre la $PSCmdlet variable automática, consulte about_Functions_CmdletBindingAttribute y about_Functions_Advanced.

$PSCommandPath

Contiene la ruta de acceso completa y el nombre de archivo del script que se está ejecutando. Esta variable es válida en todos los scripts.

$PSCulture

Contiene el nombre de la referencia cultural que se usa actualmente en el sistema operativo. La referencia cultural determina el formato de presentación de elementos como números, moneda y fechas, y se almacena en un objeto System.Globalization.CultureInfo . Use Get-Culture para mostrar la referencia cultural del equipo. $PSCulture contiene el valor de la propiedad Name .

$PSDebugContext

Durante la depuración, esta variable contiene información sobre el entorno de depuración. De lo contrario, contiene un valor NULL . Como resultado, puede usarlo para determinar si el depurador tiene control. Cuando se rellena, contiene un objeto PsDebugContext que tiene puntos de interrupción y propiedades InvocationInfo. La propiedad InvocationInfo tiene varias propiedades útiles, incluida la propiedad Location . La propiedad Location indica la ruta de acceso del script que se está depurando.

$PSEdition

Contiene el mismo valor en $PSVersionTable.PSEdition. Esta variable está disponible para su uso en los archivos de manifiesto del módulo, mientras $PSVersionTable que no lo es.

$PSHOME

Contiene la ruta de acceso completa del directorio de instalación para PowerShell, normalmente, $env:windir\System32\PowerShell\v1.0 en sistemas Windows. Puede usar esta variable en las rutas de acceso de los archivos de PowerShell. Por ejemplo, el siguiente comando busca en los temas de ayuda conceptuales la palabra Ayuda:

Select-String -Pattern Help -Path $PSHOME\en-US\*.txt

$PSItem

Igual que $_. Contiene el objeto actual en el objeto de canalización. Puede usar esta variable en comandos que realizan una acción en cada objeto de una canalización.

Para obtener más información, consulte about_PSItem.

$PSScriptRoot

Contiene la ruta de acceso completa del directorio primario del script en ejecución.

En PowerShell 2.0, esta variable solo es válida en módulos de script (.psm1). A partir de PowerShell 3.0, es válido en todos los scripts.

$PSSenderInfo

Contiene información sobre el usuario que inició la PSSession, incluida la identidad del usuario y la zona horaria del equipo de origen. Esta variable solo está disponible en PSSessions.

La $PSSenderInfo variable incluye una propiedad configurable por el usuario, ApplicationArguments, que, de forma predeterminada, contiene solo desde $PSVersionTable la sesión de origen. Para agregar datos a la propiedad ApplicationArguments, use el parámetro ApplicationArguments del New-PSSessionOption cmdlet .

$PSUICulture

Contiene el nombre de la referencia cultural de la interfaz de usuario (UI) configurada en el sistema operativo. El idioma de interfaz de usuario determina qué cadenas de texto se usan con elementos de la interfaz de usuario como menús y mensajes. Este es el valor de System.Globalization.CultureInfo.Current UICulture.Name propiedad del sistema. Para obtener el objeto System.Globalization.CultureInfo del sistema, use el Get-UICulture cmdlet .

$PSVersionTable

Contiene una tabla hash de solo lectura que muestra detalles sobre la versión de PowerShell que se ejecuta en la sesión actual. La tabla incluye los siguientes elementos:

BuildVersion : el número de compilación de la versión actual
CLRVersion : la versión de Common Language Runtime (CLR)
PSCompatibleVersions : versiones de PowerShell compatibles con la versión actual
PSEdition : esta propiedad tiene el valor de "Escritorio", para las versiones de cliente de Windows Server y Windows. Esta propiedad tiene el valor de "Core" para PowerShell que se ejecuta en Nano Server o Windows IoT.
PSRemotingProtocolVersion : la versión del protocolo de administración remota de PowerShell.
PSVersion : número de versión de PowerShell
SerializationVersion : versión del método de serialización
WSManStackVersion : el número de versión de la pila WS-Management

$PWD

Contiene un objeto path que representa la ruta de acceso completa de la ubicación del directorio actual para el espacio de ejecución de PowerShell actual.

Nota:

PowerShell admite varios espacios de ejecución por proceso. Cada espacio de ejecución tiene su propio directorio actual. Esto no es lo mismo que el directorio actual del proceso: [System.Environment]::CurrentDirectory.

$Sender

Contiene el objeto que generó este evento. Esta variable solo se rellena dentro del bloque Action de un comando de registro de eventos. El valor de esta variable también se puede encontrar en la propiedad Sender del PSEventArgs objeto que Get-Event devuelve.

$ShellId

Contiene el identificador del shell actual.

$StackTrace

Contiene un seguimiento de pila para el error más reciente.

$switch

Contiene el enumerador no los valores resultantes de una Switch instrucción . La $switch variable solo existe mientras se ejecuta la Switch instrucción; se elimina cuando la instrucción completa la switch ejecución. Para obtener más información, consulte about_Switch.

$this

La $this variable se usa en bloques de script que extienden clases para hacer referencia a la instancia de la propia clase.

El sistema de tipos extensible (ETS) de PowerShell permite agregar propiedades a clases mediante bloques de script. En un bloque de script que define una propiedad de script o un método de script, la $this variable hace referencia a una instancia de objeto de la clase que se está ampliando. Por ejemplo, PowerShell usa ETS para agregar la propiedad BaseName a la clase FileInfo .

PS> Get-ChildItem .\README.md | Get-Member BaseName | Format-List

TypeName   : System.IO.FileInfo
Name       : BaseName
MemberType : ScriptProperty
Definition : System.Object BaseName {get=if ($this.Extension.Length -gt 0)
             {$this.Name.Remove($this.Name.Length - $this.Extension.Length
             )}else{$this.Name};}

Para obtener más información, consulte about_Types.ps1xml.

En una clase de PowerShell, la $this variable hace referencia al objeto de instancia de la propia clase, lo que permite el acceso a propiedades y métodos definidos en la clase . Para más información, consulte about_Classes (Acerca de las clases).

Las clases de eventos de .NET también usan la $this variable que toman bloques de script como delegados para el controlador de eventos. En este escenario, $this representa el objeto que origina el evento, conocido como remitente del evento.

$true

Contiene True. Puede usar esta variable para representar True en comandos y scripts.

Uso de enumeradores

Las $inputvariables , $foreachy $switch son todos los enumeradores que se usan para recorrer en iteración los valores procesados por su bloque de código contenedor.

Un enumerador contiene propiedades y métodos que puede usar para avanzar o restablecer la iteración, o recuperar valores de iteración. La manipulación directa de enumeradores no se considera un procedimiento recomendado.

Dentro de los bucles, las palabras clave de control de flujo interrumpen y continúan deben preferirse.
Dentro de las funciones que aceptan entradas de canalización, se recomienda usar parámetros con los atributos ValueFromPipeline o ValueFromPipelineByPropertyName .

Para obtener más información, consulte about_Functions_Advanced_Parameters.

MoveNext

El método MoveNext hace avanzar el enumerador al siguiente elemento de la colección. MoveNext devuelve True si el enumerador se ha avanzado correctamente, False si el enumerador ha pasado el final de la colección.

Nota:

El valor booleano devuelto por MoveNext se envía al flujo de salida. Puede suprimir la salida mediante la difusión de tipos a [void] o canalización a Out-Null.

$input.MoveNext() | Out-Null

[void]$input.MoveNext()

Reset

El Reset método establece el enumerador en su posición inicial, que es antes del primer elemento de la colección.

Current

La Current propiedad obtiene el elemento de la colección, o canalización, en la posición actual del enumerador.

La Current propiedad continúa devolviendo la misma propiedad hasta que se llama a MoveNext .

Ejemplos

Ejemplo 1: Uso de la variable $input

En el ejemplo siguiente, el acceso a la $input variable borra la variable hasta la próxima vez que se ejecute el bloque de proceso. El uso del Reset método restablece la $input variable al valor de canalización actual.

function Test
{
    begin
    {
        $i = 0
    }

    process
    {
        "Iteration: $i"
        $i++
        "`tInput: $input"
        "`tAccess Again: $input"
        $input.Reset()
        "`tAfter Reset: $input"
    }
}

"one","two" | Test

Iteration: 0
    Input: one
    Access Again:
    After Reset: one
Iteration: 1
    Input: two
    Access Again:
    After Reset: two

El bloque de proceso avanza automáticamente la $input variable aunque no tenga acceso a ella.

$skip = $true
function Skip
{
    begin
    {
        $i = 0
    }

    process
    {
        "Iteration: $i"
        $i++
        if ($skip)
        {
            "`tSkipping"
            $skip = $false
        }
        else
        {
            "`tInput: $input"
        }
    }
}

"one","two" | Skip

Iteration: 0
    Skipping
Iteration: 1
    Input: two

Ejemplo 2: Uso de $input fuera del bloque de proceso

Fuera del bloque de proceso, la $input variable representa todos los valores canalizaciones a la función.

El acceso a la $input variable borra todos los valores.
El Reset método restablece toda la colección.
La Current propiedad nunca se rellena.
El método MoveNext devuelve false porque la colección no puede estar avanzada.
- Al llamar a MoveNext , se borra la $input variable.

Function All
{
    "All Values: $input"
    "Access Again: $input"
    $input.Reset()
    "After Reset: $input"
    $input.MoveNext() | Out-Null
    "After MoveNext: $input"
}

"one","two","three" | All

All Values: one two three
Access Again:
After Reset: one two three
After MoveNext:

Ejemplo 3: Uso del $input.Current propiedad

Con la Current propiedad , se puede acceder al valor de canalización actual varias veces sin usar el Reset método . El bloque de proceso no llama automáticamente al método MoveNext .

La Current propiedad nunca se rellena a menos que se llame explícitamente a MoveNext. Se Current puede acceder a la propiedad varias veces dentro del bloque de proceso sin borrar su valor.

function Current
{
    begin
    {
        $i = 0
    }

    process
    {
        "Iteration: $i"
        $i++
        "`tBefore MoveNext: $($input.Current)"
        $input.MoveNext() | Out-Null
        "`tAfter MoveNext: $($input.Current)"
        "`tAccess Again: $($input.Current)"
    }
}

"one","two" | Current

Iteration: 0
    Before MoveNext:
    After MoveNext: one
    Access Again: one
Iteration: 1
    Before MoveNext:
    After MoveNext: two
    Access Again: two

Ejemplo 4: Uso de la variable $foreach

A diferencia de la $input variable , la $foreach variable siempre representa todos los elementos de la colección cuando se obtiene acceso directamente. Utilice la Current propiedad para tener acceso al elemento de colección actual y los Reset métodos y MoveNext para cambiar su valor.

Nota:

Cada iteración del foreach bucle llama automáticamente al método MoveNext .

El siguiente bucle solo se ejecuta dos veces. En la segunda iteración, la colección se mueve al tercer elemento antes de que se complete la iteración. Después de la segunda iteración, ahora no hay más valores para iterar y el bucle finaliza.

La propiedad MoveNext no afecta a la variable elegida para recorrer en iteración la colección ($Num).

$i = 0
foreach ($num in ("one","two","three"))
{
    "Iteration: $i"
    $i++
    "`tNum: $num"
    "`tCurrent: $($foreach.Current)"

    if ($foreach.Current -eq "two")
    {
        "Before MoveNext (Current): $($foreach.Current)"
        $foreach.MoveNext() | Out-Null
        "After MoveNext (Current): $($foreach.Current)"
        "Num hasn't changed: $num"
    }
}

Iteration: 0
        Num: one
        Current: one
Iteration: 1
        Num: two
        Current: two
Before MoveNext (Current): two
After MoveNext (Current): three
Num hasn't changed: two

El uso del Reset método restablece el elemento actual de la colección. En el ejemplo siguiente se recorren los dos primeros elementos dos veces porque se llama al Reset método . Después de los dos primeros bucles, se produce un error en la if instrucción y el bucle recorre en iteración los tres elementos normalmente.

Importante

Esto podría dar lugar a un bucle infinito.

$stopLoop = 0
foreach ($num in ("one","two", "three"))
{
    ("`t" * $stopLoop) + "Current: $($foreach.Current)"

    if ($num -eq "two" -and $stopLoop -lt 2)
    {
        $foreach.Reset()
        ("`t" * $stopLoop) + "Reset Loop: $stopLoop"
        $stopLoop++
    }
}

Current: one
Current: two
Reset Loop: 0
        Current: one
        Current: two
        Reset Loop: 1
                Current: one
                Current: two
                Current: three

Ejemplo 5: Uso de la variable $switch

La $switch variable tiene exactamente las mismas reglas que la $foreach variable. En el ejemplo siguiente se muestran todos los conceptos del enumerador.

Nota:

Observe cómo nunca se ejecuta el caso NotEvaluated , aunque no haya ninguna break instrucción después del método MoveNext .

$values = "Start", "MoveNext", "NotEvaluated", "Reset", "End"
$stopInfinite = $false
switch ($values)
{
    "MoveNext" {
        "`tMoveNext"
        $switch.MoveNext() | Out-Null
        "`tAfter MoveNext: $($switch.Current)"
    }
    # This case is never evaluated.
    "NotEvaluated" {
        "`tAfterMoveNext: $($switch.Current)"
    }

    "Reset" {
        if (!$stopInfinite)
        {
            "`tReset"
            $switch.Reset()
            $stopInfinite = $true
        }
    }

    default {
        "Default (Current): $($switch.Current)"
    }
}

Default (Current): Start
    MoveNext
    After MoveNext: NotEvaluated
    Reset
Default (Current): Start
    MoveNext
    After MoveNext: NotEvaluated
Default (Current): End

Compartir a través de

about_Automatic_Variables

Descripción breve

Descripción larga

$$

$?

$^

$_

$args

$ConsoleFileName

Error$

$Event

$EventArgs

$EventSubscriber

$ExecutionContext

$false

$foreach

$HOME

$Host

$input

$LASTEXITCODE

$Matches

$MyInvocation

$NestedPromptLevel

$null

$PID

$PROFILE

$PSBoundParameters

$PSCmdlet

$PSCommandPath

$PSCulture

$PSDebugContext

$PSEdition

$PSHOME

$PSItem

$PSScriptRoot

$PSSenderInfo

$PSUICulture

$PSVersionTable

$PWD

$Sender

$ShellId

$StackTrace

$switch

$this

$true

Uso de enumeradores

MoveNext

Reset

Current

Ejemplos

Ejemplo 1: Uso de la variable $input

Ejemplo 2: Uso de $input fuera del bloque de proceso

Ejemplo 3: Uso del $input.Current propiedad

Ejemplo 4: Uso de la variable $foreach

Ejemplo 5: Uso de la variable $switch

Consulte también

Recursos adicionales