Compartir a través de

Acerca de las variables automáticas

  • Artículo

Descripción breve

Describe variables que almacenan información de estado para PowerShell. PowerShell crea y mantiene estas variables.

Descripción larga

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

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 de la última operación. Contiene True si la última operación se realizó correctamente y False si se produjo un error.

$^

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

$_

Igual a $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 o en los objetos seleccionados de una canalización.

$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 mediante 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 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 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 qué archivo se 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 objeto PSEventArgs 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. Por lo tanto, 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 se 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 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 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, vea Uso de enumeradores.

$HOME

Contiene la ruta de acceso completa del directorio principal del usuario. Esta variable es el equivalente de las "$env:homedrive$env:homepath" variables de entorno de Windows, normalmente C:\Users\<UserName>.

$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.setbackgroundcolor("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 y bloques de script (que son funciones sin nombre).

  • En una función sin un Beginbloque , Processo End , la $input variable enumera la colección de todas las entradas de la función.

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

  • En el Process bloque , la $input variable contiene el objeto que se encuentra actualmente en la canalización.

  • En el End bloque , la $input variable enumera la colección de todas las entradas de la función.

    Nota

    No puede usar la $input variable dentro del bloque Process y el bloque End en la misma función o bloque de script.

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 Uso de enumeradores.

$LastExitCode

Contiene el código de salida del último programa basado en Windows que se ejecutó.

$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, vea about_Regular_Expressions.

$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 la ruta de acceso y el nombre de archivo del script ($MyInvocation.MyCommand.Path) o el nombre de una función ($MyInvocation.MyCommand.Name) para identificar el comando actual. Esto es especialmente útil para encontrar el nombre del script actual.

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

Propiedad Descripción
PSScriptRoot Contiene la ruta de acceso completa al script que se invocó.
el comando actual. El valor de esta propiedad es
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 este
la propiedad solo se rellena cuando el autor de la llamada es
mundo".

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 aviso actual. Un valor de 0 indica el nivel de solicitud original. El valor se incrementa cuando se introduce un nivel anidado y se reduce 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 aviso. Puede crear un símbolo del sistema alternativo de PowerShell 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 ausente o no definido en comandos y scripts.

PowerShell trata $null como un objeto con un valor, es decir, como marcador de posición explícito, por lo que puede usar $null para representar un valor vacío en una serie 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 $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 no significar 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 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 solo tiene un valor en un ámbito en el que se declaran 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 $PSBoundParameters a la función Test1 . Se $PSBoundParameters 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 actualmente en uso en el sistema operativo. La referencia cultural determina el formato de presentación de elementos como números, divisa y fechas. Este es el valor de la propiedad System.Globalization.CultureInfo.CurrentCulture.Name del sistema. Para obtener el objeto System.Globalization.CultureInfo del sistema, use el Get-Culture cmdlet .

$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 indicar si el depurador tiene control. Cuando se rellena, contiene un objeto PsDebugContext que tiene las propiedades Puntos de interrupción 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.

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

Select-String -Pattern Variable -Path $pshome\*.txt

$PSItem

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

$PSScriptRoot

Contiene el directorio desde el que se ejecuta un script.

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 el $PSVersionTable elemento de 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) que está actualmente en uso 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 la propiedad System.Globalization.CultureInfo.CurrentUICulture.Name 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:

Propiedad Descripción
BuildVersion 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
PSRemotingProtocolVersion Versión remota de PowerShell
protocolo de administración.
PSVersion Número de versión de PowerShell
SerializationVersion Versión del método de serialización
WSManStackVersion Número de versión de la pila de WS-Management

$PWD

Contiene un objeto path que representa la ruta de acceso completa del directorio actual.

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

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 Uso de enumeradores.

$this

En un bloque de script que define una propiedad de script o un método de script, la $this variable hace referencia al objeto que se extiende.

$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. No se considera un procedimiento recomendado manipular directamente los enumeradores.

  • Dentro de los bucles, las palabras clave de control de flujo interrumpen y continúan deben ser preferibles.

  • 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 avanza 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 mi 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 método Reset establece el enumerador en su posición inicial, que es antes del 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 .

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 método Reset 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 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 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: Usar el $input. Propiedad actual

Mediante 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 rellenará a menos que llame explícitamente a MoveNext. Se puede tener acceso 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 $input variable, la $foreach variable 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 foreach bucle llamará 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 has not changed: $num"
    }
}

Iteration: 0
        Num: one
        Current: one
Iteration: 1
        Num: two
        Current: two
Before MoveNext (Current): two
After MoveNext (Current): three
Num has not 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 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() | Out-Null
        ("`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

Consulte también

about_Functions

about_Functions_Advanced

about_Functions_Advanced_Methods

about_Functions_Advanced_Parameters

about_Functions_OutputTypeAttribute

about_Functions_CmdletBindingAttribute

about_Hash_Tables

about_Preference_Variables

about_Splatting

about_Variables