about_CommonParameters
Se aplica a: Windows PowerShell 2.0, Windows PowerShell 3.0, Windows PowerShell 4.0
Insertar la introducción aquí.
TEMA
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. Los implementa Windows PowerShell®, no 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 efecto en todos los cmdlets. Por ejemplo, si un cmdlet no genera ninguna salida detallada, el uso del parámetro común Verbose no tiene ningún efecto.
Los parámetros comunes también están disponibles en las funciones avanzadas que usan el atributo CmdletBinding o el atributo Parameter y en todos los flujos de trabajo.
Varios parámetros comunes reemplazan los valores predeterminados del sistema o las preferencias que establezca mediante las variables de preferencia de Windows PowerShell. A diferencia de las variables de preferencia, los parámetros comunes afectan únicamente a los comandos en los que se usan.
Además de los parámetros comunes, muchos cmdlets ofrecen los parámetros de mitigación de riesgos WhatIf y Confirm. Los cmdlets que implican un riesgo para el sistema o los datos de usuario suelen ofrecer estos parámetros.
La siguiente lista muestra los parámetros comunes. Sus alias se muestran entre paréntesis.
-Debug (db)
-ErrorAction (ea)
-ErrorVariable (ev)
-OutVariable (ov)
-OutBuffer (ob)
-PipelineVariable (pv)
-Verbose (vb)
-WarningAction (wa)
-WarningVariable (wv
Los parámetros de mitigación de riesgos son:
-WhatIf (wi)
-Confirm (cf)
Para obtener más información acerca de las variables de preferencia, escriba:
help about_Preference_Variables
DESCRIPCIONES DE PARÁMETROS COMUNES
-DEBUG[:{$TRUE | $FALSE}]
Alias: db
Muestra detalles a nivel de programador acerca de la operación que realiza el comando. Este parámetro solo funciona si el comando genera un mensaje de depuración. Por ejemplo, este parámetro funciona cuando un comando contiene el cmdlet Write-Debug.
El parámetro Debug reemplaza el valor de la variable $DebugPreference para el comando actual, y establece el valor de $DebugPreference en Inquire. Dado que el valor predeterminado de la variable $DebugPreference es SilentlyContinue, los mensajes de depuración no se muestran de forma predeterminada.
Valores válidos:
$true (-Debug:$true). Has the same effect as -Debug.
$false (-Debug:$false). Suppresses the display of debugging
messages when the value of the $DebugPreference is not
SilentlyContinue (the default).
-ERRORACTION [: {CONTINUAR | OMITIR | CONSULTAR | SILENTLYCONTINUE | DETENER | SUSPENDER}]
Alias: ea
Determina cómo responde el cmdlet a un error de no terminación del comando. Este parámetro solo funciona si el comando genera un error de no terminación, como los del cmdlet Write-Error.
El parámetro ErrorAction reemplaza al valor de la variable $ErrorActionPreference para el comando actual. Dado que el valor predeterminado de la variable $ErrorActionPreference 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 sobre los errores de terminación (como la falta de datos, parámetros que no son válidos o permisos insuficientes) que impiden que un comando se complete correctamente.
Valores válidos:
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 variable automática $Error. El valor Ignore se ha introducido en Windows PowerShell 3.0.
Inquire. Muestra el mensaje de error y le pide confirmación antes de continuar la ejecución. Este valor se usa en pocas ocasiones.
SilentlyContinue. Suprime el mensaje de error y continúa ejecutando el comando.
Stop. Muestra el mensaje de error y detiene la ejecución del comando.
Suspend. Este valor solo está disponible en flujos de trabajo de Windows PowerShell. Cuando un flujo de se encuentra un error de terminación, esta preferencia de acción suspende automáticamente el trabajo para permitir la realización de una investigación detallada. Después de la investigación es posible reanudar el flujo de trabajo.
-ERRORVARIABLE [+]<VARIABLE-NAME>
Alias: ev
Almacena los mensajes de error acerca del comando en la variable especificada y en la variable automática $Error. Para obtener más información, escriba el siguiente comando:
get-help about_Automatic_Variables
De forma predeterminada, los mensajes de error nuevos 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 (+) delante del nombre de la variable.
Por ejemplo, el comando siguiente crea la variable $a 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 variable $a:
Get-Process -Id 2 -ErrorVariable +a
El comando siguiente muestra el contenido de $a:
$a
Puede usar este parámetro para crear una variable que contenga solo los mensajes de error de comandos específicos. La variable automática $Error contiene mensajes de error de todos los comandos en la sesión. Puede usar la notación de matriz, por ejemplo, $a[0] o $error[1,2] para hacer referencia a errores concretos almacenados en las variables.
-OUTBUFFER <INT32>
Alias: ob
Determina el número de objetos que se acumulan en un búfer antes de que se envíen los objetos a través de la canalización. Si se omite este parámetro, los objetos se envían cuando se generan.
Este parámetro de la administración de recursos está diseñado para usuarios avanzados. Cuando se usa este parámetro, Windows PowerShell no llama al siguiente cmdlet de la canalización hasta que el número de objetos generados es igual a OutBuffer + 1. Después, envía todos los objetos cuando se generan.
-OUTVARIABLE [+]<VARIABLE-NAME>
Alias: ov
Almacena los objetos de la salida del comando en la variable especificada y los muestra en la línea de comandos.
Para agregar la salida a la variable en lugar de reemplazar cualquier salida que ya pueda tener almacenada, escriba un signo más (+) delante del nombre de la variable.
Por ejemplo, el siguiente comando crea la variable $out y almacena el objeto de proceso en ella:
Get-Process PowerShell -OutVariable out
El comando siguiente agrega el objeto de proceso a la variable $out:
Get-Process iexplore -OutVariable +out
El comando siguiente muestra el contenido de la variable $out:
$out
-PIPELINEVARIABLE <STRING>
Alias: pv
PipelineVariable almacena el valor del elemento de canalización actual como una variable para cualquier comando con nombre que pase por la canalización.
Los valores válidos son cadenas, como para los nombres de variable.
A continuación se muestra un ejemplo de cómo funciona PipelineVariable. En este ejemplo, se agrega el parámetro PipelineVariable a un comando Foreach-Object para almacenar los resultados del comando en variables. Un intervalo de números de 1 a 10 se canaliza en el primer comando Foreach-Object, y sus resultados se almacenan en una variable denominada Left.
Los resultados del primer comando Foreach-Object se canalizan en un segundo comando Foreach-Object, que filtra los objetos devueltos por el primer comando Foreach-Object. Los resultados del segundo comando se almacenan en una variable denominada Right.
En el tercer comando Foreach-Object, los resultados de los dos primeros comandos Foreach-Object canalizados, representados por las variables, Left y Right, se procesan mediante un operador de multiplicación. El comando indica la multiplicación de los objetos almacenados en las variables de Left y Right y especifica que los resultados se deben mostrar como "miembro de intervalo Left * miembro de intervalo Right = producto".
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[:{$TRUE | $FALSE}]
Alias: vb
Muestra información detallada sobre la operación que realiza el comando. Esta información es similar a la información de un seguimiento o un registro de transacciones. Este parámetro solo funciona si el comando genera un mensaje detallado. Por ejemplo, este parámetro funciona cuando un comando contiene el cmdlet Write-Verbose.
El parámetro Verbose reemplaza al valor de la variable $VerbosePreference para el comando actual. Dado que el valor predeterminado de la variable $VerbosePreference es SilentlyContinue, no se muestran mensajes detallados de forma predeterminada.
Valores válidos:
$true (-Verbose:$true) has the same effect as -Verbose.
$false (-Verbose:$false) suppresses the display of verbose
messages. Use this parameter when the value of $VerbosePreference
is not SilentlyContinue (the default).
-WARNINGACTION[:{CONTINUE | INQUIRE | SILENTLYCONTINUE | STOP}]
Alias: wa
Determina cómo responde el cmdlet a una advertencia del comando. "Continue" es el valor predeterminado. Este parámetro solo funciona si el comando genera un mensaje de advertencia. Por ejemplo, este parámetro funciona cuando un comando contiene el cmdlet Write-Warning.
El parámetro WarningAction reemplaza al valor de la variable $WarningPreference para el comando actual. Dado que el valor predeterminado de la variable $WarningPreference es Continue, se muestran las advertencias y la ejecución continúa, a menos que use el parámetro WarningAction.
Valores válidos:
Continue. Muestra el mensaje de advertencia y continúa ejecutando el comando. "Continue" es el valor predeterminado.
Inquire. Muestra el mensaje de advertencia y solicita confirmación antes de continuar la ejecución. Este valor se usa en pocas ocasiones.
SilentlyContinue. Suprime el mensaje de advertencia y continúa ejecutando el comando.
Stop. Muestra el mensaje de advertencia y detiene la ejecución el comando.
NOTA: El parámetro WarningAction no reemplaza al valor de la variable de preferencia $WarningAction si el parámetro se usa en un comando para ejecutar un script o una función.
-WARNINGVARIABLE [+]<VARIABLE-NAME>
Alias: wv
Almacena las advertencias sobre el comando de la variable especificada.
Todas las advertencias generadas se guardan en la variable aunque no se muestren las advertencias al usuario.
Para anexar las advertencias al contenido de la variable en lugar de reemplazar las advertencias que ya tenga almacenadas, escriba un signo más (+) delante del nombre de la variable.
Por ejemplo, el comando siguiente crea la variable $a y, a continuación, almacena las advertencias en ella:
Get-Process -Id 6 -WarningVariable a
El comando siguiente agrega las advertencias a la variable $a:
Get-Process -Id 2 -WarningVariable +a
El comando siguiente muestra el contenido de $a:
$a
Puede usar este parámetro para crear una variable que contenga solo las advertencias de comandos específicos. Puede usar la notación de matriz, por ejemplo, $a[0] o $warning[1,2] para hacer referencia a advertencias específicas almacenadas en la variable.
NOTA: El parámetro WarningVariable no captura las advertencias de llamadas anidadas en funciones o scripts.
DESCRIPCIONES DE PARÁMETROS DE ADMINISTRACIÓN DE RIESGOS
-WHATIF[:{$TRUE | $FALSE}]
Alias: wi
Muestra un mensaje que describe el efecto del comando, en lugar de ejecutar el comando.
El parámetro WhatIf reemplaza al valor de la variable $WhatIfPreference para el comando actual. Dado que el valor predeterminado de la variable $WhatIfPreference es 0 (deshabilitado), el comportamiento de WhatIf no se realiza sin el parámetro WhatIf. Para obtener más información, escriba el siguiente comando:
Get-Help about_Preference_Variables
Valores válidos:
$true (-WhatIf:$true). Has the same effect as -WhatIf.
$false (-WhatIf:$false). Suppresses the automatic WhatIf behavior
that results when the value of the $WhatIfPreference variable
is 1.
Por ejemplo, el siguiente comando usa el parámetro WhatIf en un comando Remove-Item:
PS> Remove-Item Date.csv -WhatIf
En lugar de quitar el elemento, Windows PowerShell muestra las operaciones que realizaría y los elementos que se verían afectados. Este comando genera la siguiente salida:
What if: Performing operation "Remove File" on
Target "C:\ps-test\date.csv".
-CONFIRM[:{$TRUE | $FALSE}]
Alias: cf
Solicita confirmación antes de ejecutar el comando.
El parámetro Confirm reemplaza al valor de la variable $ConfirmPreference para el comando actual. El valor predeterminado es High. Para obtener más información, escriba el siguiente comando:
Get-Help about_Preference_Variables
Valores válidos:
$true (-Confirm:$true). Has the same effect as -Confirm.
$false(-Confirm:$false). Suppresses automatic confirmation,
which occurs when the value of $ConfirmPreference is less than
or equal to the estimated risk of the cmdlet.
Por ejemplo, el siguiente comando usa el parámetro Confirm con un comando Remove-Item. Antes de quitar el elemento, Windows PowerShell muestra las operaciones que realizaría y los elementos que se verían afectados, y solicita la aprobación.
PS C:\ps-test> Remove-Item tmp*.txt -Confirm
Este comando genera la siguiente salida:
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 de respuesta de Confirm son las siguientes:
Yes (Y) Perform the action.
Yes to All (A) Perform all actions and suppress subsequent
Confirm queries for this command.
No (N): Do not perform the action.
No to All (L): Do not perform any actions and suppress subsequent
Confirm queries for this command.
Suspend (S): Pause the command and create a temporary session.
Help (?) Display help for these options.
La opción Suspend pone el comando en espera y crea una sesión anidada temporal en la que puede trabajar hasta que esté preparado para elegir una opción de Confirm. El símbolo del sistema para la sesión anidada tiene dos operadores exponenciales 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 de Confirm del comando original, escriba "exit".
En el ejemplo siguiente se usa la opción Suspend (S) para detener un comando temporalmente mientras el usuario consulta la ayuda de un parámetro del comando. Después de obtener la información necesaria, el usuario escribe "exit" para finalizar la petición anidada y, a continuación, selecciona la respuesta Yes (y) para la consulta de Confirm.
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 (default 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
VEA TAMBIÉN
about_Preference_Variables
Write-Debug
Write-Warning
Write-Error
Write-Verbose