Acerca de 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. Se implementan mediante PowerShell, 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 parámetro común Detallado 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 , y en todos los flujos de trabajo.
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.
Además de los parámetros comunes, muchos cmdlets ofrecen los parámetros whatIf y Confirm risk mitigation. Los cmdlets que implican riesgos para el sistema o para los datos de usuario suelen ofrecer estos parámetros.
En la lista siguiente se muestran los parámetros comunes. Sus alias se muestran entre paréntesis.
- Debug (db)
- ErrorAction (ea)
- ErrorVariable (ev)
- InformationAction (infa)
- InformationVariable (iv)
- OutVariable (ov)
- OutBuffer (ob)
- PipelineVariable (pv)
- Detallado (vb)
- WarningAction (wa)
- WarningVariable (wv)
Los parámetros de mitigación de riesgos son:
- WhatIf (wi)
- Confirmar (cf)
Para obtener más información, consulte about_Preference_Variables.
DESCRIPCIONES COMUNES DE PARÁMETROS
Depuración
El alias de Depuración es db.
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 .
El parámetro Debug invalida el valor de la $DebugPreference variable para el comando actual, estableciendo el valor de $DebugPreference en Continue. Dado que el valor predeterminado de la $DebugPreference variable es SilentlyContinue, los mensajes de depuración no se muestran de forma predeterminada.
-Debug:$true tiene el mismo efecto que -Debug. Use -Debug:$false para suprimir la presentación de mensajes de depuración cuando $DebugPreference no sea SilentlyContinue, que es el valor predeterminado.
ErrorAction
El alias de ErrorAction es ea.
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 .
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.
-ErrorAction:Continue muestra el mensaje de error y continúa ejecutando el comando. Continue es el valor predeterminado.
-ErrorAction: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.
-ErrorAction:Inquire muestra el mensaje de error y le pide confirmación antes de continuar la ejecución. Este valor rara vez se usa.
-ErrorAction:SilentlyContinue suprime el mensaje de error y continúa ejecutando el comando.
-ErrorAction:Stop muestra el mensaje de error y deja de ejecutar el comando.
-ErrorAction:Suspend no se admite en PowerShell Core, ya que solo está disponible para los flujos de trabajo.
Nota
El parámetro ErrorAction invalida, pero no reemplaza el valor de la $ErrorAction variable de preferencia cuando se usa el parámetro en un comando para ejecutar un script o una función.
ErrorVariable
El alias de ErrorVariable es ev.
ErrorVariable almacena mensajes de error sobre el comando en la variable especificada y en la $Error variable automática. Para obtener más información, escriba el siguiente comando:
Get-Help about_Automatic_Variables
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, 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 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. 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
El alias de InformationAction es ia.
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, vea about_Preference_Variables.
-InformationAction:Stop detiene un comando o script en una aparición del Write-Information comando.
-InformationAction: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 al flujo de información.
-InformationAction:Inquire muestra el mensaje informativo que especifique en un Write-Information comando y, a continuación, pregunta si desea continuar.
-InformationAction:Continue muestra el mensaje informativo y continúa ejecutándose.
-InformationAction:Suspend no se admite en PowerShell Core, ya que solo está disponible para los flujos de trabajo.
-InformationAction: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 se usa el parámetro en un comando para ejecutar un script o una función.
InformationVariable
El alias de InformationVariable es iv.
Se introdujo en PowerShell 5.0. Dentro del comando o script en el que se usa, el parámetro común InformationVariable almacena en una variable una cadena que especifique agregando el Write-Information comando . Write-Information los valores se muestran en función del valor del parámetro común InformationAction ; Si no agrega el parámetro común InformationAction , Write-Information las cadenas se muestran en función del valor de la $InformationPreference variable de preferencia. Para obtener más información sobre $InformationPreference, vea about_Preference_Variables.
OutBuffer
El alias de OutBuffer es ob y toma un valor System.Int32 .
Determina el número de objetos que se van a acumular en un búfer antes de que se envíen objetos a través de la canalización. Si omite este parámetro, los objetos se envían a medida que se generan.
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 pantallas entre los ForEach-Object bloques de 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
El alias de OutVariable es ov.
Almacena los objetos de salida del comando en la variable especificada además de enviar la salida a lo largo de la canalización.
Para agregar la salida a la variable, en lugar de reemplazar cualquier salida que ya se pueda almacenar 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 siguiente comando agrega el objeto process a la $out variable :
Get-Process iexplore -OutVariable +out
El comando siguiente muestra el contenido de la $out variable:
$out
Nota
La variable creada por el parámetro OutVariable es .[System.Collections.ArrayList]
PipelineVariable
El alias de PipelineVariable es pv y toma un valor de cadena .
PipelineVariable almacena el valor del elemento de canalización actual como una variable, para cualquier comando con nombre a medida que fluye a través de la canalización.
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 10, se canalizan al primer Foreach-Object comando, los resultados de los cuales se almacenan en una variable denominada Left.
Los resultados del primer Foreach-Object comando se canalizan a un segundo Foreach-Object comando, que filtra los objetos devueltos por el primer Foreach-Object comando. Los resultados del segundo comando se almacenan en una variable denominada Right.
En el tercer Foreach-Object comando, los resultados de los dos Foreach-Object primeros comandos canalizaciones, representados por las variables Izquierda y Derecha, se procesan mediante un operador de multiplicación. El comando indica a los objetos almacenados en las variables Left y Right que se van a multiplicar y especifica que los resultados deben mostrarse como "Left range member * Right range member = product".
1..10 | Foreach-Object -PipelineVariable Left -Process { $_ } |
Foreach-Object -PV Right -Process { 1..10 } |
Foreach-Object -Process { "$Left * $Right = " + ($Left*$Right) }
1 * 1 = 1
1 * 2 = 2
1 * 3 = 3
1 * 4 = 4
1 * 5 = 5
...
Verbose
El alias de Verbose es vb.
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 en 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 .
El parámetro Verbose 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
El alias de WarningAction es wa.
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 .
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, se muestran advertencias y la ejecución continúa a menos que use el parámetro WarningAction .
-WarningAction:Continue muestra los mensajes de advertencia y continúa ejecutando el comando. Continue es el valor predeterminado.
-WarningAction:Inquire muestra el mensaje de advertencia y le pide confirmación antes de continuar con la ejecución. Este valor rara vez se usa.
-WarningAction:SilentlyContinue suprime el mensaje de advertencia y continúa ejecutando el comando.
-WarningAction: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 se usa el parámetro en un comando para ejecutar un script o una función.
WarningVariable
El alias de WarningVariable es wv.
Almacena advertencias sobre el comando en la variable especificada.
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 siguiente comando agrega cualquier advertencia 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
El parámetro WarningVariable no captura advertencias de llamadas anidadas en funciones o scripts.
Descripciones de parámetros de administración de riesgos
WhatIf
El alias de WhatIf es wi.
Muestra un mensaje que describe el efecto del comando, en lugar de ejecutar el comando.
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 whatIf no se realiza sin el parámetro WhatIf . Para obtener más información, escriba el siguiente comando:
Get-Help about_Preference_Variables
-WhatIf:$true tiene el mismo efecto que -WhatIf.
-WhatIf:$false suprime el comportamiento automático de WhatIf que da como resultado cuando el valor de la $WhatIfPreference variable es 1.
Por ejemplo, el siguiente comando 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
El alias de Confirm es cf.
Le solicita confirmación antes de ejecutar el comando.
El parámetro Confirm invalida el valor de la $ConfirmPreference variable para el comando actual. El valor predeterminado es true. Para obtener más información, escriba el siguiente comando:
Get-Help about_Preference_Variables
-Confirm:$true tiene el mismo efecto que -Confirm.
-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 siguiente comando usa el parámetro Confirm 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 opciones confirmar respuesta son las siguientes:
| Response | Resultado |
|---|---|
| Sí (Y) | Realice la acción. |
| Sí a todos (A) | Realizar todas las acciones y suprimir las consultas Confirm posteriores |
| para este comando. | |
| No (N): | No realice la acción. |
| No a todos (L): | No realice ninguna acción y suprima la confirmación posterior |
| consulta para este comando. | |
| Suspender (S): | Pause el comando y cree una sesión temporal. |
| Ayuda (?) | 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 opción Confirmar . 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 opciones Confirmar para el 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 consulta Confirmar.
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
PALABRAS CLAVE
about_Common_Parameters