about_CommonParameters

Descripción breve

Describe los parámetros que se pueden usar con cualquier cmdlet.

Descripción larga

Los parámetros comunes son un conjunto de parámetros de cmdlet que puede usar con cualquier cmdlet. PowerShell las implementa, no por el desarrollador de cmdlets, y están disponibles automáticamente para cualquier cmdlet.

Puede usar los parámetros comunes con cualquier cmdlet, pero es posible que no tengan ningún efecto en todos los cmdlets. Por ejemplo, si un cmdlet no genera ninguna verbose salida, el uso del Verbose parámetro común no tiene ningún efecto.

Los parámetros comunes también están disponibles en funciones avanzadas que usan el CmdletBinding atributo o el Parameter atributo . Al usar estos atributos, PowerShell agrega automáticamente los parámetros comunes. No se pueden crear parámetros que usen los mismos nombres que los parámetros comunes.

Varios parámetros comunes invalidan los valores predeterminados o preferencias del sistema que se establecen mediante las variables de preferencia de PowerShell. A diferencia de las variables de preferencia, los parámetros comunes solo afectan a los comandos en los que se usan.

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

En la lista siguiente se muestran los parámetros comunes. Sus alias aparecen entre paréntesis.

• Debug (db)
• ErrorAction (ea)
• ErrorVariable (ev)
• InformationAction (infa)
• InformationVariable (iv)
• OutVariable (ov)
• OutBuffer (ob)
• PipelineVariable (pv)
• ProgressAction (proga)
• Verbose (vb)
• WarningAction (wa)
• WarningVariable (wv)

Los parámetros Action son valores de tipo ActionPreference . ActionPreference es una enumeración con los siguientes valores:

Puede usar el nombre o el valor con el parámetro .

Además de los parámetros comunes, muchos cmdlets ofrecen parámetros de mitigación de riesgos. Los cmdlets que implican riesgos para el sistema o para los datos de usuario suelen ofrecer estos parámetros.

Los parámetros de mitigación de riesgos son:

• WhatIf (wi)
• Confirm (cf)

Descripciones de parámetros comunes

-Debug

Muestra detalles de nivel de programador sobre la operación realizada por el comando. Este parámetro solo funciona cuando el comando genera un mensaje de depuración. Por ejemplo, este parámetro funciona cuando un comando contiene el Write-Debug cmdlet .

Type: SwitchParameter
Aliases: db
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

De forma predeterminada, los mensajes de depuración no se muestran porque el valor de la $DebugPreference variable es SilentlyContinue.

El Debug parámetro invalida el valor de la $DebugPreference variable para el comando actual, estableciendo el valor de $DebugPreference en Continue.

-Debug:$true tiene el mismo efecto que -Debug. Use -Debug:$false para suprimir la visualización de mensajes de depuración cuando $DebugPreference no sea SilentlyContinue, que es el valor predeterminado.

-ErrorAction

Determina cómo responde el cmdlet a un error de no terminación del comando . Este parámetro solo funciona cuando el comando genera un error de no terminación, como los del Write-Error cmdlet .

Type: ActionPreference
Aliases: ea
Accepted values: Break, Suspend, Ignore, Inquire, Continue, Stop, SilentlyContinue
Required: False
Position: Named
Default value: Depends on preference variable
Accept pipeline input: False
Accept wildcard characters: False

El parámetro ErrorAction invalida el valor de la $ErrorActionPreference variable para el comando actual. Dado que el valor predeterminado de la $ErrorActionPreference variable es Continue, se muestran los mensajes de error y la ejecución continúa a menos que use el parámetro ErrorAction .

El parámetro ErrorAction no tiene ningún efecto en los errores de terminación (como datos que faltan, parámetros que no son válidos o permisos insuficientes) que impiden que un comando se complete correctamente.

• Break Escribe el depurador cuando se produce un error o se produce una excepción.
• Continue muestra el mensaje de error y continúa ejecutando el comando. Continue es el valor predeterminado.
• Ignore suprime el mensaje de error y continúa ejecutando el comando. A diferencia de SilentlyContinue, Ignore no agrega el mensaje de error a la $Error variable automática. El valor Ignore se introduce en PowerShell 3.0.
• Inquire muestra el mensaje de error y le pide confirmación antes de continuar la ejecución. Este valor rara vez se usa.
• SilentlyContinue suprime el mensaje de error y continúa ejecutando el comando.
• Stop muestra el mensaje de error y deja de ejecutar el comando.
• Suspend solo está disponible para los flujos de trabajo que no se admiten en PowerShell 6 y versiones posteriores.

-ErrorVariable

Los registros de error se almacenan automáticamente en la $Error variable automática. Para obtener más información, vea about_Automatic_Variables.

Cuando se usa el parámetro ErrorVariable en un comando, PowerShell también almacena los registros de error emitidos por el comando en la variable especificada por el parámetro .

Type: String
Aliases: ev
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

De forma predeterminada, los nuevos mensajes de error sobrescriben los mensajes de error que ya están almacenados en la variable. Para anexar el mensaje de error al contenido de la variable, coloque un signo más (+) antes del nombre de la variable.

Por ejemplo, el siguiente comando crea la $a variable y, a continuación, almacena los errores en ella:

Get-Process -Id 6 -ErrorVariable a

El comando siguiente agrega los mensajes de error a la $a variable :

Get-Process -Id 2 -ErrorVariable +a

El siguiente comando muestra el contenido de $a:

$a

Puede usar este parámetro para crear una variable que contenga solo mensajes de error de comandos específicos y no afecte al comportamiento de la $Error variable automática. La $Error variable automática contiene mensajes de error de todos los comandos de la sesión. Puede usar la notación de matriz, como $a[0] o $error[1,2] para hacer referencia a errores específicos almacenados en las variables.

-InformationAction

Se introdujo en PowerShell 5.0. Dentro del comando o script en el que se usa, el parámetro común InformationAction invalida el valor de la $InformationPreference variable de preferencia, que de forma predeterminada se establece en SilentlyContinue. Cuando se usa Write-Information en un script con InformationAction, Write-Information los valores se muestran en función del valor del parámetro InformationAction. Para obtener más información sobre $InformationPreference, consulte about_Preference_Variables.

Type: ActionPreference
Aliases: infa
Accepted values: Break, Suspend, Ignore, Inquire, Continue, Stop, SilentlyContinue
Required: False
Position: Named
Default value: Depends on preference variable
Accept pipeline input: False
Accept wildcard characters: False

• Break Escribe el depurador en una aparición del Write-Information comando.
• Stop detiene un comando o script en una aparición del Write-Information comando.
• Ignore suprime el mensaje informativo y continúa ejecutando el comando . A diferencia de SilentlyContinue, Ignore olvida completamente el mensaje informativo; no agrega el mensaje informativo a la secuencia de información.
• Inquire muestra el mensaje informativo que especifique en un Write-Information comando y, a continuación, pregunta si desea continuar.
• Continue muestra el mensaje informativo y continúa ejecutándose.
• Suspend no se admite en PowerShell 6 y versiones posteriores, ya que solo está disponible para los flujos de trabajo.
• SilentlyContinue no se muestra ningún efecto, ya que el mensaje informativo no se muestra (valor predeterminado) y el script continúa sin interrupción.

-InformationVariable

Se introdujo en PowerShell 5.0. Cuando se usa el parámetro común InformationVariable , los registros de información se almacenan en la variable especificada por el parámetro . Y el cmdlet de PowerShell puede escribir registros de información en el flujo de información . También puede usar el Write-Information cmdlet para escribir registros de información.

Los registros de información se muestran como mensajes en la consola de forma predeterminada. Puede controlar la presentación del registro de información mediante el parámetro común InformationAction . También puede cambiar el comportamiento mediante la variable de $InformationPreference preferencia. Para obtener más información sobre $InformationPreference, consulte about_Preference_Variables.

Type: String
Aliases: iv
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

De forma predeterminada, el nuevo registro de información sobrescribe los valores que ya están almacenados en la variable . Para anexar el mensaje de error al contenido de la variable, coloque un signo más (+) antes del nombre de la variable.

-OutBuffer

Determina el número de objetos que se van a acumular en un búfer antes de que los objetos se envíen a través de la canalización. Si omite este parámetro, los objetos se envían a medida que se generan.

Type: Int32
Aliases: ob
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

Este parámetro de administración de recursos está diseñado para usuarios avanzados. Cuando se usa este parámetro, PowerShell envía datos al siguiente cmdlet en lotes de OutBuffer + 1.

En el ejemplo siguiente se alternan las visualizaciones entre los bloques de ForEach-Object proceso que usan el Write-Host cmdlet . La presentación alterna en lotes de 2 o OutBuffer + 1.

1..4 | ForEach-Object {
        Write-Host "$($_): First"; $_
      } -OutBuffer 1 | ForEach-Object {
                        Write-Host "$($_): Second" }

1: First
2: First
1: Second
2: Second
3: First
4: First
3: Second
4: Second

-OutVariable

Almacena los objetos de salida del comando en la variable especificada además de enviar la salida a lo largo de la canalización.

Type: String
Aliases: ov
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

Para agregar la salida a la variable, en lugar de reemplazar cualquier salida que ya esté almacenada allí, escriba un signo más (+) antes del nombre de la variable.

Por ejemplo, el siguiente comando crea la $out variable y almacena el objeto de proceso en él:

Get-Process PowerShell -OutVariable out

El comando siguiente agrega el objeto de proceso a la $out variable :

Get-Process iexplore -OutVariable +out

El siguiente comando muestra el contenido de la $out variable:

$out

-PipelineVariable

PipelineVariable permite el acceso al valor más reciente pasado al siguiente segmento de canalización por el comando que usa este parámetro. Cualquier comando de la canalización puede tener acceso al valor mediante pipelineVariable denominado. El valor se asigna a la variable cuando se pasa al siguiente segmento de canalización. Esto facilita el uso de PipelineVariable que una variable temporal específica, que podría ser necesario asignar en varias ubicaciones.

A diferencia $_ de o $PSItem, el uso de PipelineVariable permite que cualquier comando de canalización acceda a los valores de canalización pasados (y guardados) por comandos distintos del comando inmediatamente anterior. Los comandos de canalización pueden acceder al último valor canalización mientras se procesa el siguiente elemento pasando por la canalización. Esto permite que un comando devuelva su salida a un comando anterior (o a sí mismo).

Type: String
Aliases: pv
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

Los valores válidos son cadenas, igual que para los nombres de variable.

A continuación se muestra un ejemplo de cómo funciona PipelineVariable . En este ejemplo, el parámetro PipelineVariable se agrega a un Foreach-Object comando para almacenar los resultados del comando en variables. Un intervalo de números, de 1 a 5, se canalizan al primer Foreach-Object comando, los resultados de los cuales se almacenan en una variable denominada $temp.

Los resultados del primer Foreach-Object comando se canalizan en un segundo Foreach-Object comando, que muestra los valores actuales de $temp y $_.

# Create a variable named $temp
$temp=8
Get-Variable temp
# Note that the variable just created isn't available on the
# pipeline when -PipelineVariable creates the same variable name
1..5 | ForEach-Object -PipelineVariable temp -Begin {
    Write-Host "Step1[BEGIN]:`$temp=$temp"
} -Process {
  Write-Host "Step1[PROCESS]:`$temp=$temp - `$_=$_"
  Write-Output $_
} | ForEach-Object {
  Write-Host "`tStep2[PROCESS]:`$temp=$temp - `$_=$_"
}
# The $temp variable is deleted when the pipeline finishes
Get-Variable temp

Name                           Value
----                           -----
temp                           8

Step1[BEGIN]:$temp=
Step1[PROCESS]:$temp= - $_=1
        Step2[PROCESS]:$temp=1 - $_=1
Step1[PROCESS]:$temp=1 - $_=2
        Step2[PROCESS]:$temp=2 - $_=2
Step1[PROCESS]:$temp=2 - $_=3
        Step2[PROCESS]:$temp=3 - $_=3
Step1[PROCESS]:$temp=3 - $_=4
        Step2[PROCESS]:$temp=4 - $_=4
Step1[PROCESS]:$temp=4 - $_=5
        Step2[PROCESS]:$temp=5 - $_=5

Name                           Value
----                           -----
temp

-ProgressAction

Determina cómo PowerShell responde a las actualizaciones de progreso generadas por un script, cmdlet o proveedor, como las barras de progreso generadas por el cmdlet Write-Progress . El Write-Progress cmdlet crea barras de progreso que muestran el estado de un comando. El parámetro ProgressAction se agregó en PowerShell 7.4.

El parámetro ProgressAction toma uno de los ActionPreference valores de enumeración: SilentlyContinue, Stop, Continue, Inquire, Ignore, o BreakSuspend.

Los valores válidos son los siguientes:

• Break Escribe el depurador en una aparición del Write-Progress comando.
• Stop: no muestra la barra de progreso. En su lugar, muestra un mensaje de error y deja de ejecutarse.
• Inquire: no muestra la barra de progreso. Solicita permiso para continuar. Si responde con Y o A, muestra la barra de progreso.
• Continue: (Valor predeterminado) Muestra la barra de progreso y continúa con la ejecución.
• SilentlyContinue: ejecuta el comando , pero no muestra la barra de progreso.

Type: ActionPreference
Aliases: proga
Accepted values: Break, Suspend, Ignore, Inquire, Continue, Stop, SilentlyContinue
Required: False
Position: Named
Default value: Depends on preference variable
Accept pipeline input: False
Accept wildcard characters: False

-Verbose

Muestra información detallada sobre la operación realizada por el comando . Esta información es similar a la información de un seguimiento o de un registro de transacciones. Este parámetro solo funciona cuando el comando genera un verbose mensaje. Por ejemplo, este parámetro funciona cuando un comando contiene el Write-Verbose cmdlet .

Type: SwitchParameter
Aliases: vb
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

El Verbose parámetro invalida el valor de la $VerbosePreference variable para el comando actual. Dado que el valor predeterminado de la $VerbosePreference variable es SilentlyContinue, verbose los mensajes no se muestran de forma predeterminada.

• -Verbose:$true tiene el mismo efecto que -Verbose
• -Verbose:$false suprime la presentación de verbose mensajes. Use este parámetro cuando el valor de $VerbosePreference no sea SilentlyContinue (valor predeterminado).

-WarningAction

Determina cómo responde el cmdlet a una advertencia del comando . Continue es el valor predeterminado. Este parámetro solo funciona cuando el comando genera un mensaje de advertencia. Por ejemplo, este parámetro funciona cuando un comando contiene el Write-Warning cmdlet .

Type: ActionPreference
Aliases: wa
Accepted values: Break, Suspend, Ignore, Inquire, Continue, Stop, SilentlyContinue
Required: False
Position: Named
Default value: Depends on preference variable
Accept pipeline input: False
Accept wildcard characters: False

El parámetro WarningAction invalida el valor de la $WarningPreference variable para el comando actual. Dado que el valor predeterminado de la $WarningPreference variable es Continue, las advertencias se muestran y la ejecución continúa a menos que use el parámetro WarningAction .

• Break escribe el depurador cuando se produce una advertencia.
• Continue muestra los mensajes de advertencia y continúa ejecutando el comando. Continue es el valor predeterminado.
• Inquire muestra el mensaje de advertencia y le pide confirmación antes de continuar la ejecución. Este valor rara vez se usa.
• SilentlyContinue suprime el mensaje de advertencia y continúa ejecutando el comando .
• Stop muestra el mensaje de advertencia y deja de ejecutar el comando.

-WarningVariable

Almacena registros de advertencia sobre el comando en la variable especificada.

Type: String
Aliases: wv
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

Todas las advertencias generadas se guardan en la variable incluso si las advertencias no se muestran al usuario.

Para anexar las advertencias al contenido de la variable, en lugar de reemplazar las advertencias que podrían estar almacenadas allí, escriba un signo más (+) antes del nombre de la variable.

Por ejemplo, el siguiente comando crea la $a variable y, a continuación, almacena las advertencias en ella:

Get-Process -Id 6 -WarningVariable a

El comando siguiente agrega advertencias a la $a variable :

Get-Process -Id 2 -WarningVariable +a

El siguiente comando muestra el contenido de $a:

$a

Puede usar este parámetro para crear una variable que contenga solo advertencias de comandos específicos. Puede usar la notación de matriz, como $a[0] o $warning[1,2] para hacer referencia a advertencias específicas almacenadas en la variable.

Descripciones de parámetros de administración de riesgos

-WhatIf

Muestra un mensaje que describe el efecto del comando, en lugar de ejecutar el comando.

Type: SwitchParameter
Aliases: wi
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

El parámetro WhatIf invalida el valor de la $WhatIfPreference variable para el comando actual. Dado que el valor predeterminado de la $WhatIfPreference variable es 0 (deshabilitado), el comportamiento de WhatIf no se realiza sin el parámetro WhatIf . Para obtener más información, consulte about_Preference_Variables.

• $true tiene el mismo efecto que -WhatIf.
• $false suprime el comportamiento automático de WhatIf que se produce cuando el valor de la $WhatIfPreference variable es 1.

Por ejemplo, el comando siguiente usa el -WhatIf parámetro en un Remove-Item comando :

Remove-Item Date.csv -WhatIf

En lugar de quitar el elemento, PowerShell enumera las operaciones que haría y los elementos que se verían afectados. Este comando genera el siguiente resultado:

What if: Performing operation "Remove File" on
Target "C:\ps-test\date.csv".

-Confirm

Le solicita confirmación antes de ejecutar el comando.

Type: SwitchParameter
Aliases: cf
Required: False
Position: Named
Default value: Depends on preference variable
Accept pipeline input: False
Accept wildcard characters: False

El Confirm parámetro invalida el valor de la $ConfirmPreference variable para el comando actual. El valor predeterminado es true. Para obtener más información, consulte about_Preference_Variables.

• $true tiene el mismo efecto que -Confirm.
• $false suprime la confirmación automática, que se produce cuando el valor de $ConfirmPreference es menor o igual que el riesgo estimado del cmdlet.

Por ejemplo, el comando siguiente usa el Confirm parámetro con un Remove-Item comando . Antes de quitar el elemento, PowerShell enumera las operaciones que haría y los elementos que se verían afectados y solicita su aprobación.

PS C:\ps-test> Remove-Item tmp*.txt -Confirm

Confirm
Are you sure you want to perform this action?
Performing operation "Remove File" on Target " C:\ps-test\tmp1.txt
[Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend
[?] Help (default is "Y"):

Las Confirm opciones de respuesta son las siguientes:

La opción Suspender coloca el comando en espera y crea una sesión anidada temporal en la que puede trabajar hasta que esté listo para elegir una Confirm opción. El símbolo del sistema de la sesión anidada tiene dos símbolos de intercalación adicionales (>>) para indicar que es una operación secundaria del comando primario original. Puede ejecutar comandos y scripts en la sesión anidada. Para finalizar la sesión anidada y volver a las Confirm opciones del comando original, escriba "exit".

En el ejemplo siguiente, la opción Suspender (S) se usa para detener temporalmente un comando mientras el usuario comprueba la ayuda de un parámetro de comando. Después de obtener la información necesaria, el usuario escribe "exit" para finalizar el aviso anidado y, a continuación, selecciona la respuesta Sí (y) a la Confirm consulta.

PS C:\ps-test> New-Item -ItemType File -Name Test.txt -Confirm

Confirm
Are you sure you want to perform this action?

Performing operation "Create File" on Target "Destination:
C:\ps-test\test.txt".
[Y] Yes [A] Yes to All [N] No [L] No to All [S] Suspend [?] Help (default
is "Y"): s

PS C:\ps-test> Get-Help New-Item -Parameter ItemType

-ItemType <string>
Specifies the provider-specified type of the new item.

Required?                    false
Position?                    named
Default value
Accept pipeline input?       true (ByPropertyName)
Accept wildcard characters?  false

PS C:\ps-test> exit

Confirm
Are you sure you want to perform this action?
Performing operation "Create File" on Target "Destination: C:\ps-test\test
.txt".
[Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (defau
lt is "Y"): y

Directory: C:\ps-test

Mode                LastWriteTime     Length Name
----                -------------     ------ ----
-a---         8/27/2010   2:41 PM          0 test.txt

Consulte también

• about_Preference_Variables
• Escribir-Debug
• Write-Error
• Escribir-Verbose
• Write-Warning