about_Parameters_Default_Values
Descripción breve
Describe cómo establecer valores predeterminados personalizados para parámetros de cmdlet, funciones avanzadas y scripts.
Descripción larga
La variable de preferencia $PSDefaultParameterValues permite especificar valores de parámetro predeterminados personalizados para cualquier cmdlet, función avanzada o script que use el atributo CmdletBinding. Los valores definidos se usan a menos que especifique otros valores en la línea de comandos.
Esta característica es útil en los escenarios siguientes:
- especificar el mismo valor de parámetro cada vez que se usa el comando
- especificar un valor de parámetro determinado que es difícil de recordar, como un nombre de servidor de correo electrónico o un GUID del proyecto
La variable $PSDefaultParameterValues no tiene ningún valor predeterminado. Para guardar la configuración para usarla en sesiones futuras, agregue la asignación de variables al perfil de PowerShell.
$PSDefaultParameterValues se introdujo en PowerShell 3.0.
Sintaxis
La variable $PSDefaultParameterValues es un tipo de objeto de System.Management.Automation.DefaultParameterDictionary. El tipo DefaultParameterDictionary es una tabla hash con validación adicional para el formato de las claves. La tabla hash contiene pares clave-valor donde:
- la clave tiene el formato
CommandName:ParameterName - el valor es el valor predeterminado para el parámetro o un ScriptBlock que devuelve el valor predeterminado.
Para la clave , el CommandName debe ser el nombre de un cmdlet, una función avanzada o un archivo de script que use el atributo CmdletBinding. El nombre del script debe coincidir con el nombre notificado por (Get-Command -Name .\script.ps1).Name.
Nota
PowerShell no te impide especificar un alias para el nombre del comando . Sin embargo, hay casos en los que la definición se omite o produce un error. Debe evitar definir los valores predeterminados para los alias de comando.
El valor puede ser un objeto de un tipo compatible con el parámetro o un ScriptBlock que devuelve dicho valor. Cuando el valor es un bloque de script, PowerShell evalúa el bloque de script y usa el resultado para el valor del parámetro. Si el parámetro especificado espera un tipo de ScriptBlock, debe incluir el valor en otro conjunto de llaves. Cuando PowerShell evalúa el ScriptBlock externo, el resultado es el ScriptBlock interno. El ScriptBlock interno se convierte en el nuevo valor de parámetro predeterminado.
Por ejemplo:
$PSDefaultParameterValues = @{
'Invoke-Command:ScriptBlock' = { {Get-Process} }
}
Ejemplos
Use los métodos Add() y Remove() para agregar o quitar un par clave-valor específico de $PSDefaultParameterValues sin sobrescribir otros pares clave-valor existentes.
$PSDefaultParameterValues.Add('CmdletName:ParameterName', 'DefaultValue')
$PSDefaultParameterValues.Remove('CmdletName:ParameterName')
Use la indexación o el acceso a miembros para cambiar el valor de un par clave-valor existente. Por ejemplo:
$PSDefaultParameterValues.'CommandName:ParameterName'='DefaultValue2'
$PSDefaultParameterValues['CommandName:ParameterName']='DefaultValue1'
Asignar valores a $PSDefaultParameterValues
Para definir valores predeterminados para los parámetros de cmdlet, asigne una tabla hash que contenga los pares clave-valor adecuados a la variable $PSDefaultParameterValues.
La tabla hash puede contener varios pares clave-valor. En este ejemplo se establecen valores predeterminados para las claves de Send-MailMessage:SmtpServer y Get-WinEvent:LogName.
$PSDefaultParameterValues = @{
'Send-MailMessage:SmtpServer'='Server123'
'Get-WinEvent:LogName'='Microsoft-Windows-PrintService/Operational'
}
Los nombres de cmdlet y parámetro pueden contener caracteres comodín. Use $true y $false para establecer valores para los parámetros switch, como Verbose. En este ejemplo se establece el parámetro común Verbose a $true para todos los comandos.
$PSDefaultParameterValues = @{'*:Verbose'=$true}
Si un parámetro acepta varios valores, puede proporcionar varios valores predeterminados mediante una matriz. En este ejemplo se establece el valor predeterminado de la clave de Invoke-Command:ComputerName en una matriz que contiene los valores de cadena Server01 y Server02.
$PSDefaultParameterValues = @{
'Invoke-Command:ComputerName' = 'Server01','Server02'
}
Visualización de valores definidos
Tenga en cuenta la siguiente definición de $PSDefaultParameterValues:
$PSDefaultParameterValues = @{
'Send-MailMessage:SmtpServer' = 'Server123'
'Get-WinEvent:LogName' = 'Microsoft-Windows-PrintService/Operational'
'Get-*:Verbose' = $true
}
Para ver los valores definidos, introduzca $PSDefaultParameterValues en el símbolo del sistema.
PS> $PSDefaultParameterValues
Name Value
---- -----
Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational
Get-*:Verbose True
Send-MailMessage:SmtpServer Server123
Puede usar la indexación o el acceso a miembros para obtener un valor específico.
PS> $PSDefaultParameterValues['Send-MailMessage:SmtpServer'] # index notation
Server123
PS> $PSDefaultParameterValues.'Get-*:Verbose' # member access notation
True
Uso de un bloque de script para el valor predeterminado
Puede usar un bloque de script para especificar valores predeterminados diferentes para un parámetro en condiciones diferentes. PowerShell evalúa el bloque de script y usa el resultado como valor de parámetro predeterminado.
La clave Format-Table:AutoSize establece que cambia el parámetro a un valor predeterminado de $true La instrucción if contiene una condición que el $Host.Name debe ser ConsoleHost.
$PSDefaultParameterValues = @{
'Format-Table:AutoSize' = { if ($Host.Name -eq 'ConsoleHost'){$true} }
}
Si un parámetro acepta un valor de ScriptBlock, incluya el ScriptBlock en otro conjunto de llaves. Cuando PowerShell evalúa el ScriptBlock externo, el resultado es el ScriptBlock interno. El ScriptBlock interno se convierte en el nuevo valor de parámetro predeterminado.
$PSDefaultParameterValues = @{
'Invoke-Command:ScriptBlock' = { {Get-EventLog -Log System} }
}
Agregar valores a una variable de $PSDefaultParameterValues existente
Para agregar un valor a $PSDefaultParameterValues, use el método Add(). Agregar un valor no afecta a los valores existentes de la tabla hash. Use una coma (,) para separar la clave de del valor de .
$PSDefaultParameterValues.Add('Get-Process:Name', 'PowerShell')
La tabla hash creada en el ejemplo anterior se actualiza con un nuevo par clave-valor.
PS> $PSDefaultParameterValues
Name Value
---- -----
Get-Process:Name PowerShell
Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational
Get-*:Verbose True
Send-MailMessage:SmtpServer Server123
Eliminación de un valor de $PSDefaultParameterValues
Para quitar un valor de $PSDefaultParameterValues, use el método Remove().
Quitar un valor no afecta a los valores existentes de la tabla hash.
En este ejemplo se quita el par clave-valor que se agregó en el ejemplo anterior.
PS> $PSDefaultParameterValues.Remove('Get-Process:Name')
PS> $PSDefaultParameterValues
Name Value
---- -----
Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational
Get-*:Verbose True
Send-MailMessage:SmtpServer Server123
Cambiar un valor en $PSDefaultParameterValues
Use la indexación o el acceso de miembro para cambiar el valor predeterminado de un par clave-valor existente. En este ejemplo, el valor predeterminado de la clave Send-MailMessage:SmtpServer se cambia a un nuevo valor de ServerXYZ.
PS> $PSDefaultParameterValues['Send-MailMessage:SmtpServer']='ServerXYZ'
PS> $PSDefaultParameterValues
Name Value
---- -----
Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational
Get-*:Verbose True
Send-MailMessage:SmtpServer ServerXYZ
Deshabilitar o volver a habilitar $PSDefaultParameterValues
Puede deshabilitar temporalmente y volver a habilitar $PSDefaultParameterValues.
Deshabilitar $PSDefaultParameterValues es útil si ejecuta scripts que necesitan valores de parámetro predeterminados diferentes.
Para deshabilitar $PSDefaultParameterValues, agregue una clave de Disabled con un valor de $true. Los valores de $PSDefaultParameterValues se conservan, pero no se usan.
PS> $PSDefaultParameterValues.Add('Disabled', $true)
PS> $PSDefaultParameterValues
Name Value
---- -----
Disabled True
Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational
Get-*:Verbose True
Send-MailMessage:SmtpServer ServerXYZ
Para volver a habilitar $PSDefaultParameterValues, quite la clave de Disabled o cambie el valor de la clave de Disabled a $false.
PS> $PSDefaultParameterValues.Disabled = $false
PS> $PSDefaultParameterValues
Name Value
---- -----
Disabled False
Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational
Get-*:Verbose True
Send-MailMessage:SmtpServer ServerXYZ
