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 salida detallada, 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 atributo CmdletBinding o el atributo Parameter .

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:

NOMBRE	Valor
Break	6
Suspend	5
Ignore	4
Inquire	3
Continue	2
Stop	1
SilentlyContinue	0

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.

Nota:

El parámetro ErrorAction invalida, pero no reemplaza el valor de la $ErrorActionPreference variable cuando el parámetro se usa en un comando para ejecutar un script o una función.

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

Nota:

La variable de error personalizada contiene todos los errores generados por el comando, incluidos los errores de llamadas a funciones o scripts anidados.

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

Nota:

El parámetro InformationAction invalida, pero no reemplaza el valor de la $InformationAction variable de preferencia cuando el parámetro se usa en un comando para ejecutar un script o una funció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.

Nota:

La variable de información contiene todos los mensajes de información generados por el comando, incluidos los mensajes de información de llamadas a funciones o scripts anidados.

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

Nota:

La variable creada por el parámetro OutVariable es .[System.Collections.ArrayList]

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

Nota:

Las funciones avanzadas pueden tener hasta tres bloques de script: begin, processy end. Cuando se usa el parámetro PipelineVariable con funciones avanzadas, solo se asignan valores del primer bloque de script definido a la variable a medida que se ejecuta la función. Para obtener más información, consulte Funciones avanzadas. PowerShell 7.2 corrige este comportamiento.

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.

Precaución

PipelineVariable se limita a la canalización en la que se invoca. Las variables fuera de la canalización, que usan el mismo nombre, se borran antes de que se ejecute la canalización. PipelineVariable sale del ámbito cuando finaliza la canalización. Si varios comandos dentro de la canalización especifican la misma variable PipelineVariable , solo hay una variable compartida. Esa variable se actualiza con la salida canalización más reciente del comando que especifica la variable.

Algunos comandos de bloqueo recopilan todos los elementos de canalización antes de generar cualquier salida, por ejemplo Sort-Object o Select-Object -Last. Cualquier pipelineVariable asignado en un comando antes de este comando de bloqueo siempre contiene el elemento canalizado final del comando anterior cuando se usa en un comando después del comando de bloqueo.

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 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 mensaje detallado. 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, los mensajes detallados no se muestran de forma predeterminada.

• -Verbose:$true tiene el mismo efecto que -Verbose
• -Verbose:$false suprime la presentación de mensajes detallados. 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.

Nota:

El parámetro WarningAction invalida, pero no reemplaza el valor de la $WarningAction variable de preferencia cuando el parámetro se usa en un comando para ejecutar un script o una función.

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

Nota:

La variable de advertencia contiene todas las advertencias generadas por el comando, incluidas las advertencias de llamadas a funciones o scripts anidados.

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:

Respuesta	Resultado
Yes (Y)	Realice la acción.
Yes to All (A)	Realizar todas las acciones y suprimir posteriores Confirm
	consultas para este comando.
No (N):	No realice la acción.
No to All (L):	No realice ninguna acción ni suprima las siguientes acciones
	Confirm consultas para este comando.
Suspend (S):	Pause el comando y cree una sesión temporal.
Help (?)	Mostrar ayuda para estas opciones.

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