Compartir a través de

about_Automatic_Variables

Descripción breve

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

Descripción larga

Conceptualmente, la mayoría de estas variables se consideran de solo lectura. Aunque se puede escribir en ellas, por compatibilidad con versiones anteriores no se debe escribir en ellas.

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

$$

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 los cmdlets y funciones avanzadas que se ejecutan en varias etapas de una canalización, por ejemplo, en los bloques process y end, llamar a this.WriteError() o $PSCmdlet.WriteError(), respectivamente, en cualquier momento establece $? en False, al igual que lo hace this.ThrowTerminatingError() y $PSCmdlet.ThrowTerminatingError().

El cmdlet Write-Error siempre establece $? en False inmediatamente después de su ejecución, pero no establece $? en False en una función que lo llame.

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

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

Test-WriteError:
Line |
   7 |  Test-WriteError
     |  ~~~~~~~~~~~~~~~
     | Bad
The $? variable is: False
Now the $? variable is: True

Para este último propósito, se debe usar $PSCmdlet.WriteError() 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, incluir una sentencia dentro de paréntesis (...), sintaxis de subexpresión $(...) o una expresión de matriz @(...) siempre restablecía $? a True. Por ejemplo, (Write-Error) 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 a $PSItem. Contiene el objeto actual del 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 scriptblock. Al crear una función, puede declarar los parámetros con la palabra clave param 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 variable $args contiene objetos que representan los argumentos de evento del evento que se está procesando. 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 SourceArgs del objeto PSEventArgs 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 cmdlet Export-Console para exportar nombres de complemento a un archivo de consola.

Cuando se usa el cmdlet Export-Console 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.

$EnabledExperimentalFeatures

Contiene una lista de nombres de las características experimentales que están habilitadas.

$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 matriz de $Error, use el parámetro común ErrorAction con un valor de Ignore. Para obtener más información, vea about_CommonParameters.

$Event

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

$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 bloque Action de un comando de registro de eventos. El valor de esta variable también se puede encontrar en la propiedad SourceEventArgs del objeto PSEventArgs que Get-Event devuelve.

$EventSubscriber

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

$ExecutionContext

Contiene un EngineIntrinsicsics objeto 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 variable $foreach solo existe mientras se ejecuta el bucle foreach; 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, vea Using Enumerators.

$HOME

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

Importante

Windows puede redirigir la ubicación del perfil del usuario. Esto significa que es posible que $HOME no tengan el mismo valor que "$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".

Nota

La configuración de color de $Host.PrivateData se ha reemplazado por la variable de preferencia $PSStyle. Para obtener más información, vea about_ANSI_Terminals.

$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 scripts (que son funciones sin nombre) y archivos de script (que se guardan como bloques de scripts).

  • En una función sin un bloque begin, processo end, la variable $input enumera la colección de todas las entradas de la función.

  • En el bloque begin, la variable $input no contiene datos.

  • En el bloque process, la variable $input contiene el objeto actual de la canalización.

  • En el bloque end, la variable $input 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 scriptblock.

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

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, vea Using Enumerators.

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

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

$IsCoreCLR

Contiene $true si la sesión actual se ejecuta en el entorno de ejecución de .NET Core (CoreCLR). De lo contrario, contiene $false.

$IsLinux

Contiene $true si la sesión actual se ejecuta en un sistema operativo Linux. De lo contrario, contiene $false.

$IsMacOS

Contiene $true si la sesión actual se ejecuta en un sistema operativo macOS. De lo contrario, contiene $false.

$IsWindows

Contiene $true si la sesión actual se ejecuta en un sistema operativo Windows. De lo contrario, contiene $false.

$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 $LASTEXITCODE depende de cómo se llamó al script y de si se usó la palabra clave exit:

  • Cuando un script usa la palabra clave exit:

    $LASTEXITCODE se establece con el valor especificado por la palabra clave exit. 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 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 palabra clave exit

  • Cuando se llama a un script con mediante el parámetro File , se establece en:

    • 1 si el script finalizó debido a una excepción
    • Valor especificado por la palabra clave exit, si se usa en el script.
    • 0 si el script se completó correctamente

  • Cuando se llama a un script con pwsh 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 puso $? en $false
    • 0 si el script se completó correctamente y el resultado del último comando establece $? a $true

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

$Matches

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

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

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

Nota

Cuando $Matches se rellena en una sesión, conserva el valor coincidente hasta que se invalida mediante otra coincidencia. Si se vuelve a usar -match 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 quien llama 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 quien llama es un script.

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

$NestedPromptLevel

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

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

Cuando se introduce una solicitud anidada, PowerShell pausa el comando actual, guarda el contexto de ejecución e incrementa el valor de la variable $NestedPromptLevel. Para crear indicadores de comandos anidados adicionales (hasta 128 niveles) o volver al indicador de comando original, complete el comando o escriba exit.

La variable $NestedPromptLevel ayuda a realizar un seguimiento del nivel de aviso. 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

3

Si canaliza la variable $null al cmdlet ForEach-Object, 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 puede usar $null para representar sin 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 variable $null como marcador de posición, puede usarla en scripts como el siguiente, que no funcionaría si $null se omitían.

$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 el $PSBoundParameters a la función Test1. El $PSBoundParameters se muestra con el formato de Key y Value.

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 de 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 variable automática de $PSCmdlet, 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

A partir de PowerShell 7, $PSCulture refleja la cultura del espacio de ejecución (sesión) de PowerShell actual. Si se cambia el idioma en un espacio de ejecución de PowerShell, se actualiza el valor $PSCulture de ese espacio de ejecución.

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. Usa Get-Culture para mostrar la cultura 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 las propiedades Breakpoints e 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 que $PSVersionTable no.

$PSHOME

Contiene la ruta de acceso completa del directorio de instalación para PowerShell, normalmente, C:\Program Files\PowerShell\7 en sistemas Windows. Puede usar esta variable en las rutas de acceso de los archivos de PowerShell. Por ejemplo, el comando siguiente busca en los temas de Ayuda conceptuales la palabra Ayuda:

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

$PSItem

Igual a $_. Contiene el objeto actual del 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 variable $PSSenderInfo incluye una propiedad configurable por el usuario, ApplicationArguments, que, de forma predeterminada, contiene solo el $PSVersionTable de la sesión de origen. Para agregar datos a la propiedad ApplicationArguments, use el parámetro ApplicationArguments del cmdlet New-PSSessionOption.

$PSUICulture

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

$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:

  • PSVersion: el número de versión de PowerShell
  • PSEdition Esta propiedad tiene el valor de "Desktop" para PowerShell 4 y versiones posteriores, así como PowerShell 5.1 en ediciones completas de Windows. Esta propiedad tiene el valor de Core para PowerShell 6 y versiones posteriores, así como Windows PowerShell 5.1 en ediciones de superficie reducida como Windows Nano Server o Windows IoT.
  • gitCommitId: el identificador de confirmación de los archivos de origen, en GitHub,
  • OS - Descripción del sistema operativo en el que se ejecuta PowerShell.
  • Platform: plataforma en la que se ejecuta el sistema operativo. El valor en Linux y macOS es unix. Consulte $IsMacOS y $IsLinux.
  • PSCompatibleVersions: versiones de PowerShell compatibles con la versión actual
  • PSRemotingProtocolVersion: la versión del protocolo de administración remota de PowerShell.
  • SerializationVersion: la versión del método de serialización
  • WSManStackVersion: el número de versión de la pila de WS-Management

$PWD

Contiene un objeto de ruta que representa la ruta 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 objeto PSEventArgs que Get-Event devuelve.

$ShellId

Contiene el identificador del shell actual.

$StackTrace

Contiene una traza de pila para el error más reciente.

$switch

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

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, vea Using Enumerators.

$this

La $this variable se usa en los bloques de script que extienden las 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 scriptsblocks. En un scriptblock 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, vea about_Types.ps1xml.

En una clase de PowerShell, la variable $this 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 obtener más información, consulte about_Classes.

Las clases de eventos de .NET también usan la $this variable que toma los bloqueos 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 variables $input, $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, se deben preferir las palabras clave de control de flujo break y continue.

  • Dentro de las funciones que aceptan entradas de canalización, se recomienda usar parámetros con los atributos de ValueFromPipeline o ValueFromPipelineByPropertyName.

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

Avanzar

El método MoveNext avanza el enumerador al siguiente elemento de la colección. MoveNext devuelve True si el enumerador avanzó correctamente, False si el enumerador alcanzó el final de la colección.

Nota

El valor booleano que devuelve MoveNext se envía al flujo de salida. Puede suprimir la salida con la conversión al tipo [void] o canalizándola a Out-Null.

$input.MoveNext() | Out-Null

[void]$input.MoveNext()

Reset

El método Reset establece el enumerador a su posición inicial, que es anterior al primer elemento de la colección.

Current

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

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

Examples

Ejemplo 1: Uso de la variable $input

En el ejemplo siguiente, el acceso a la variable $input borra la variable hasta la próxima vez que se ejecute el bloque de proceso. El uso del método Reset restablece la variable $input 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 variable $input incluso si no tiene 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 variable $input representa todos los valores transmitidos hacia la función.

  • El acceso a la variable $input borra todos los valores.
  • El método Reset restablece toda la colección.
  • La propiedad Current nunca se rellena.
  • El método MoveNext devuelve false porque la colección no puede avanzar.
    • Al llamar a MoveNext se borra la variable $input.
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: Usar la propiedadCurrent de $input.

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

La propiedad Current nunca se rellena a menos que se llame explícitamente a MoveNext. Se puede acceder a la propiedad Current 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 variable $input, la variable $foreach siempre representa todos los elementos de la colección cuando se accede directamente. Utilice la propiedad Current para tener acceso al elemento de colección actual y los métodos Reset y MoveNext para cambiar su valor.

Nota

Cada iteración del bucle foreach 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 método Reset restablece el elemento actual de la colección. En el ejemplo siguiente se recorren los dos primeros elementos dos veces porque se llama al método Reset. Después de los dos primeros bucles, se produce un error en la instrucción if 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 variable $switch tiene las mismas reglas que la variable $foreach. En el ejemplo siguiente se muestran todos los conceptos del enumerador.

Nota

Nota cómo el caso de NotEvaluated nunca se ejecuta, aunque no haya ninguna instrucción break 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

Consulte también

  • Last updated on