TEMA about_CommonParameters

DESCRIPCIN BREVE Describe los parmetros que se pueden utilizar con cualquier cmdlet.

DESCRIPCIN DETALLADA Los parmetros comunes son un conjunto de parmetros de cmdlet que se pueden utilizar con cualquier cmdlet. Los implementa Windows PowerShell y no el programador del cmdlet. Estn disponibles automticamente para cualquier cmdlet.

Los parmetros comunes se pueden utilizar con cualquier cmdlet, pero puede que no surtan efecto en todos ellos. Por ejemplo, si un cmdlet no genera ninguna salida detallada, utilizar el parmetro comn Verbose no tendr ningn efecto.

Varios parmetros comunes invalidan valores predeterminados del sistema o preferencias establecidas mediante las variables de preferencia de Windows PowerShell. A diferencia de las variables de preferencia, los parmetros comunes afectan solamente a los comandos en los que se utilizan. Adems de los parmetros comunes, muchos cmdlets proporcionan los parmetros de mitigacin de riesgos WhatIf y Confirm. Los cmdlets que implican riesgos para el sistema o los datos del usuario suelen proporcionar estos parmetros.

Los parmetros comunes son:

-Verbose -Debug -WarningAction -WarningVariable -ErrorAction -ErrorVariable -OutVariable -OutBuffer

Los parmetros de mitigacin de riesgos son:

-WhatIf -Confirm

Para obtener ms informacin sobre las variables de preferencia, escriba:

help about_preference_variables

Descripciones de los parmetros comunes

-Verbose[:{$true | $false}]

Muestra informacin detallada sobre la operacin realizada por el comando. Esta informacin se parece a la informacin de un registro de seguimiento o de transacciones. Este parmetro funciona solamente cuando el comando genera un mensaje detallado. Por ejemplo, este parmetro funciona cuando un comando contiene el cmdlet Write-Verbose. El parmetro Verbose invalida el valor de la variable $VerbosePreference para el comando actual. Dado que el valor predeterminado de la variable $VerbosePreference es SilentlyContinue, de forma predeterminada no se muestran los mensajes detallados.

Valores vlidos:

$true (-Verbose:$true) tiene el mismo efecto que -Verbose.

$false (-Verbose:$false) suprime la presentacin de los mensajes detallados. Este parmetro se utiliza cuando el valor de $VerbosePreference no es SilentlyContinue (el valor predeterminado).

-Debug[:{$true | $false}]

Muestra detalles de nivel de programacin sobre la operacin realizada por el comando. Este parmetro funciona nicamente cuando el comando genera un mensaje de depuracin. Por ejemplo, este parmetro funciona cuando un comando contiene el cmdlet Write-Debug. El parmetro Debug invalida el valor de la variable $DebugPreference para el comando actual. Dado que el valor predeterminado de la variable $DebugPreference es SilentlyContinue, de forma predeterminada no se muestran los mensajes de depuracin. Valores vlidos:

$true (-Debug:$true). Tiene el mismo efecto que -Debug.

$false (-Debug:$false). Suprime la presentacin de los mensajes de depuracin cuando el valor de $DebugPreference no es SilentlyContinue (el valor predeterminado).

-WarningAction[:{SilentlyContinue | Continue | Inquire | Stop}]

Determina cmo responde el cmdlet a una advertencia procedente del comando. El valor predeterminado es "Continue". Este parmetro funciona nicamente cuando el comando genera un mensaje de advertencia. Por ejemplo, este parmetro funciona cuando un comando contiene el cmdlet Write-Warning.

El parmetro WarningAction invalida el valor de la variable $WarningPreference para el comando actual. Puesto que el valor predeterminado de la variable $WarningPreference es Continue, se muestran las advertencias y la ejecucin contina a menos que se utilice el parmetro WarningAction.

Valores vlidos:

SilentlyContinue. Suprime el mensaje de advertencia y sigue ejecutando el comando.

Continue. Muestra el mensaje de advertencia y sigue ejecutando el comando. El valor predeterminado es "Continue". Inquire. Muestra el mensaje de advertencia y pide confirmacin antes de continuar la ejecucin. Casi nunca se utiliza este valor.

Stop. Muestra el mensaje de advertencia y detiene la ejecucin del comando.

-WarningVariable [+]

Almacena las advertencias sobre el comando en la variable especificada.

Para anexar las advertencias al contenido de la variable, en lugar de reemplazar las que puedan estar almacenadas en ella, se escribe un signo ms (+) antes del nombre de la variable.

Por ejemplo, el comando siguiente crea la variable $a y, a continuacin, almacena todas las advertencias en ella:

get-process -id 6 -WarningVariable a

El comando siguiente agrega todas las advertencias a la variable $a:

get-process -id 2 -WarningVariable +a

El comando siguiente muestra el contenido de $a:

$a

Puede utilizar este parmetro para crear una variable que contenga nicamente las advertencias correspondientes a comandos concretos. Puede utilizar la notacin de matriz, como $a[0] o $warning[1,2] para hacer referencia a las advertencias concretas que estn almacenadas en la variable.

-ErrorAction[:{SilentlyContinue | Continue | Inquire | Stop)]

Determina cmo responde el cmdlet cuando se produce un error que no es de terminacin. Este parmetro funciona nicamente cuando el comando genera un mensaje de depuracin. Por ejemplo, este parmetro funciona cuando un comando contiene el cmdlet Write-Error.

El parmetro ErrorAction invalida el 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 ejecucin contina a menos que se utilice el parmetro ErrorAction.

El parmetro ErrorAction no tiene ningn efecto en los errores de terminacin (tales como datos que faltan, parmetros no vlidos o permisos insuficientes) que impiden que un comando se complete correctamente.

Valores vlidos:

SilentlyContinue. Suprime el mensaje de error y sigue ejecutando el comando.

Continue. Muestra el mensaje de error y sigue ejecutando el comando. El valor predeterminado es "Continue". Inquire. Muestra el mensaje de error y pide confirmacin antes de continuar la ejecucin. Casi nunca se utiliza este valor.

Stop. Muestra el mensaje de error y detiene la ejecucin del comando.

-ErrorVariable [+]

Almacena los mensajes de error del comando en la variable especificada y en la variable automtica $Error. Para obtener ms informacin, escriba el comando siguiente:

get-help about_automatic_variables

De forma predeterminada, los mensajes de error nuevos sobrescriben los que ya estn almacenados en la variable. Para anexar el mensaje de error al contenido de la variable, se escribe un signo ms (+) antes del nombre de la variable.

Por ejemplo, el comando siguiente crea la variable $a y, a continuacin, almacena todos los errores en ella:

get-process -id 6 -ErrorVariable a

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

get-process -id 2 -ErrorVariable +a

El comando siguiente muestra el contenido de $a:

$a

Este parmetro se puede utilizar para crear una variable que contenga solamente mensajes de error de comandos concretos. La variable automtica $Error contiene los mensajes de error de todos los comandos de la sesin. Se puede utilizar la notacin de matriz, como $a[0] o $error[1,2] para hacer referencia a errores concretos almacenados en las variables.

-OutVariable [+]

Almacena objetos de salida del comando en la variable especificada y los muestra en la lnea de comandos.

Para agregar la salida a la variable en lugar de reemplazar lo que ya est almacenado en ella, se escribe un signo ms (+) antes del nombre de la variable.

Por ejemplo, el comando siguiente 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

-OutBuffer

Determina el nmero de objetos para que se acumularn en un bfer antes de enviarlos a travs de la canalizacin. Si se omite este

parmetro, los objetos se envan a medida que se generan. Este parmetro de administracin de recursos est diseado para usuarios expertos. Cuando se utiliza este parmetro, Windows PowerShell no llama al prximo cmdlet de la canalizacin hasta que el nmero de objetos generados sea igual al valor de OutBuffer + 1. A partir de entonces, enva todos los objetos a medida que se generan.

Descripciones de los parmetros de administracin de riesgos

-WhatIf[:{$true | $false}] Muestra un mensaje en el que se describe el efecto del comando en lugar de ejecutar el comando.

El parmetro WhatIf invalida el 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 lleva a cabo si no est presente el parmetro WhatIf. Para obtener ms informacin, escriba el comando siguiente:

get-help about_preference_variables

Valores vlidos:

$true (-WhatIf:$true). Tiene el mismo efecto que -WhatIf. $false (-WhatIf:$false). Suprime el comportamiento automtico de WhatIf que se produce cuando el valor de la variable $WhatIfPreference es 1.

Por ejemplo, el comando siguiente utiliza el parmetro WhatIf en un comando Remove-Item:

PS> remove-item date.csv -whatif

En lugar de quitar el elemento, Windows PowerShell hace una lista de las operaciones que realizara y de los elementos que se veran afectados. Este comando genera la salida siguiente:

Whatif: Realizando la operacin "Quitar archivo" en el destino "C:\ps-test\date.csv".

-Confirm[:{$true | $false}] Solicita confirmacin antes de ejecutar el comando.

El parmetro Confirm invalida el valor de la variable $ConfirmPreference para el comando actual. El valor predeterminado es High. Para obtener ms informacin, escriba el comando siguiente:

get-help about_preference_variables

Valores vlidos:

$true (-WhatIf:$true). Tiene el mismo efecto que -Confirm.

$false(-Confirm:$false). Suprime la confirmacin automtica que se produce cuando el valor de $ConfirmPreference es menor o igual que el riesgo estimado del cmdlet.

Por ejemplo, el comando siguiente utiliza el parmetro Confirm con un comando Remove-Item. Antes de quitar el elemento, Windows PowerShell muestra una lista de las operaciones que realizara y de los elementos que se veran afectados, y pide autorizacin para ello.

PS C:\ps-test> remove-item tmp*.txt -confirm

Este comando genera la salida siguiente:

Confirmar Est seguro de que desea realizar esta accin? Realizando operacin "Quitar archivo" en el destino " C:\ps- test\tmp1.txt [S] S [O] S a todo [N] No [T] No a todo [S] Suspender [?] Ayuda (el valor predeterminado es "S"):

VEA TAMBIN about_Preference_Variables Write-Debug Write-Warning Write-Error Write-Verbose