about_Parameters_Default_Values

Descripción breve

Describe cómo establecer valores predeterminados personalizados para parámetros de cmdlet y funciones avanzadas.

Descripción larga

La $PSDefaultParameterValues variable de preferencia permite especificar valores predeterminados personalizados para cualquier cmdlet o función avanzada. Los cmdlets y las funciones avanzadas usan el valor predeterminado personalizado a menos que especifique otro valor en el comando.

Los autores de cmdlets y funciones avanzadas establecen valores predeterminados estándar para sus parámetros. Normalmente, los valores predeterminados estándar son útiles, pero es posible que no sean adecuados para todos los entornos.

Esta característica es especialmente útil cuando se debe especificar el mismo valor de parámetro alternativo casi cada vez que se usa el comando o cuando es difícil recordar un valor de parámetro determinado, como un nombre de servidor de correo electrónico o un GUID de proyecto.

Si el valor predeterminado deseado varía de forma predecible, puede especificar un bloque de script que proporcione valores predeterminados diferentes para un parámetro en condiciones diferentes.

$PSDefaultParameterValues se introdujo en PowerShell 3.0.

Sintaxis

La $PSDefaultParameterValues variable es una tabla hash que valida el formato de las claves como un tipo de objeto de System.Management.Automation.DefaultParameterDictionary. La tabla hash contiene pares clave-valor . Una clave tiene el formato CmdletName:ParameterName. Un valor es defaultValue o ScriptBlock asignado a la clave.

La sintaxis de la $PSDefaultParameterValues variable de preferencia es la siguiente:

$PSDefaultParameterValues=@{"CmdletName:ParameterName"="DefaultValue"}

$PSDefaultParameterValues=@{ "CmdletName:ParameterName"={{ScriptBlock}} }

$PSDefaultParameterValues["Disabled"]=$True | $False

Los caracteres comodín se permiten en los valores CmdletName y ParameterName .

Para establecer, cambiar, agregar o quitar un par clave-valor específico de $PSDefaultParameterValues, use los métodos para editar una tabla hash estándar. Por ejemplo, los métodos Add y Remove . Estos métodos no sobrescriben otros valores de la tabla hash.

Hay otra sintaxis que no sobrescribe una tabla hash existente $PSDefaultParameterValues . Para agregar o cambiar un par clave/valor específico, use la sintaxis siguiente:

$PSDefaultParameterValues["CmdletName:ParameterName"]="DefaultValue"

CmdletName debe ser el nombre de un cmdlet o el nombre de una función avanzada que usa el atributo CmdletBinding. No se puede usar $PSDefaultParameterValues para especificar valores predeterminados para scripts o funciones simples.

DefaultValue puede ser un objeto o un bloque de script. Si el valor es un bloque de script, PowerShell evalúa el bloque de script y usa el resultado como valor de parámetro. Cuando el parámetro especificado acepta un valor de bloque de script, incluya el valor de bloque de script en un segundo conjunto de llaves, como:

$PSDefaultParameterValues=@{ "Invoke-Command:ScriptBlock"={{Get-Process}} }

Para obtener más información, vea los documentos siguientes:

Ejemplos

Establecimiento de $PSDefaultParameterValues

$PSDefaultParameterValues es una variable de preferencia, por lo que solo existe en la sesión en la que se establece. No tiene ningún valor predeterminado.

Para establecer $PSDefaultParameterValues, escriba el nombre de la variable y uno o varios pares clave-valor . Si ejecuta otro $PSDefaultParameterValues comando, sobrescribe la tabla hash existente.

Para obtener ejemplos sobre cómo cambiar pares clave-valor sin sobrescribir los valores de tabla hash existentes, vea How to add values to $PSDefaultParameterValues or How to change values in $PSDefaultParameterValues.

Para guardar $PSDefaultParameterValues en sesiones futuras, agregue un $PSDefaultParameterValues comando al perfil de PowerShell. Para obtener más información, consulte about_Profiles.

Establecimiento de un valor predeterminado personalizado

El par Clave-valor establece la Send-MailMessage:SmtpServer clave en un valor predeterminado personalizado de Server123.

$PSDefaultParameterValues = @{
  "Send-MailMessage:SmtpServer"="Server123"
}

Establecimiento de valores predeterminados para varios parámetros

Para establecer valores predeterminados para varios parámetros, separe cada par clave-valor con punto y coma (;). Las Send-MailMessage:SmtpServer claves y Get-WinEvent:LogName se establecen en valores predeterminados personalizados.

$PSDefaultParameterValues = @{
  "Send-MailMessage:SmtpServer"="Server123";
  "Get-WinEvent:LogName"="Microsoft-Windows-PrintService/Operational"
}

Uso de caracteres comodín y parámetros switch

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. El parámetro Verbose del parámetro común se establece $True en para todos los comandos.

$PSDefaultParameterValues = @{"*:Verbose"=$True}

Usar una matriz para el valor predeterminado

Si un parámetro puede aceptar varios valores, una matriz puede establecer varios valores como valores predeterminados. El valor predeterminado de la Invoke-Command:ComputerName clave se establece en un valor de matriz de Server01 y Server02.

$PSDefaultParameterValues = @{
  "Invoke-Command:ComputerName"="Server01","Server02"
}

Uso de un bloque de script

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 Format-Table:AutoSize clave establece que cambia el parámetro a un valor predeterminado de True. La If instrucción contiene una condición que $host.Name debe ser la consola de PowerShell, ConsoleHost.

$PSDefaultParameterValues=@{
  "Format-Table:AutoSize"={if ($host.Name -eq "ConsoleHost"){$True}}
}

Si un parámetro acepta un valor de bloque de script, incluya el bloque de script en un conjunto adicional de llaves. Cuando PowerShell evalúa el bloque de script externo, el resultado es el bloque de script interno y se establece como el valor de parámetro predeterminado.

Clave Invoke-Command:ScriptBlock establecida en un valor predeterminado del registro de eventos del sistema porque el bloque de script se incluye en un segundo conjunto de llaves. El resultado del bloque de script se pasa al Invoke-Command cmdlet .

$PSDefaultParameterValues=@{
  "Invoke-Command:ScriptBlock"={{Get-EventLog -Log System}}
}

Cómo obtener $PSDefaultParameterValues

Los valores de la tabla hash se muestran escribiendo $PSDefaultParameterValues en el símbolo del sistema de PowerShell.

Una $PSDefaultParameterValues tabla hash se establece con tres pares clave-valor . Esta tabla hash se usa en los ejemplos siguientes que describen cómo agregar, cambiar y quitar valores de $PSDefaultParameterValues.

PS> $PSDefaultParameterValues = @{
  "Send-MailMessage:SmtpServer"="Server123"
  "Get-WinEvent:LogName"="Microsoft-Windows-PrintService/Operational"
  "Get-*:Verbose"=$True
}

PS> $PSDefaultParameterValues

Name                           Value
----                           -----
Get-WinEvent:LogName           Microsoft-Windows-PrintService/Operational
Get-*:Verbose                  True
Send-MailMessage:SmtpServer    Server123

Para obtener el valor de una clave específica CmdletName:ParameterName , use la sintaxis siguiente:

$PSDefaultParameterValues["CmdletName:ParameterName"]

Por ejemplo, para obtener el valor de la Send-MailMessage:SmtpServer clave.

PS> $PSDefaultParameterValues["Send-MailMessage:SmtpServer"]
Server123

Adición de valores a $PSDefaultParameterValues

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 del valor. La sintaxis siguiente muestra cómo usar el método Add para $PSDefaultParameterValues.

PS> $PSDefaultParameterValues.Add("CmdletName:ParameterName", "DefaultValue")

La tabla hash creada en el ejemplo anterior se actualiza con un nuevo par clave-valor . El método Add establece la Get-Process:Name clave en el valor de PowerShell.

$PSDefaultParameterValues.Add("Get-Process:Name", "PowerShell")

La siguiente sintaxis logra el mismo resultado.

$PSDefaultParameterValues["Get-Process:Name"]="PowerShell"

La $PSDefaultParameterValues variable muestra la tabla hash actualizada. Se agregó la Get-Process:Name clave.

PS> $PSDefaultParameterValues

Name                           Value
----                           -----
Get-Process:Name               PowerShell
Get-WinEvent:LogName           Microsoft-Windows-PrintService/Operational
Get-*:Verbose                  True
Send-MailMessage:SmtpServer    Server123

Cómo quitar valores de $PSDefaultParameterValues

Para quitar un valor de $PSDefaultParameterValues, use el método Remove de tablas hash. Quitar un valor no afecta a los valores existentes de la tabla hash.

La sintaxis siguiente muestra cómo usar el método Remove en $PSDefaultParameterValues.

PS> $PSDefaultParameterValues.Remove("CmdletName:ParameterName")

En este ejemplo, la tabla hash creada en el ejemplo anterior se actualiza para quitar un par clave-valor . El método Remove quita la Get-Process:Name clave.

$PSDefaultParameterValues.Remove("Get-Process:Name")

La $PSDefaultParameterValues variable muestra la tabla hash actualizada. Se quitó la Get-Process:Name clave.

PS> $PSDefaultParameterValues

Name                           Value
----                           -----
Get-WinEvent:LogName           Microsoft-Windows-PrintService/Operational
Get-*:Verbose                  True
Send-MailMessage:SmtpServer    Server123

Cambio de valores en $PSDefaultParameterValues

Los cambios en un valor específico no afectan a los valores de tabla hash existentes. Para cambiar un par clave/valor específico en $PSDefaultParameterValues, use la sintaxis siguiente:

PS> $PSDefaultParameterValues["CmdletName:ParameterName"]="DefaultValue"

En este ejemplo, la tabla hash creada en el ejemplo anterior se actualiza para cambiar un par clave-valor . El siguiente comando cambia la Send-MailMessage:SmtpServer clave a un nuevo valor de ServerXYZ.

$PSDefaultParameterValues["Send-MailMessage:SmtpServer"]="ServerXYZ"

La $PSDefaultParameterValues variable muestra la tabla hash actualizada. La Send-MailMessage:SmtpServer clave se cambió a un nuevo valor.

PS> $PSDefaultParameterValues

Name                           Value
----                           -----
Get-WinEvent:LogName           Microsoft-Windows-PrintService/Operational
Get-*:Verbose                  True
Send-MailMessage:SmtpServer    ServerXYZ

Cómo deshabilitar y 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 true. Los valores de $PSDefaultParameterValues se conservan, pero no son efectivos.

PS> $PSDefaultParameterValues.Add("Disabled", $True)

La siguiente sintaxis logra el mismo resultado.

PS> $PSDefaultParameterValues["Disabled"]=$True

La $PSDefaultParameterValues variable muestra la tabla hash actualizada con el valor de la Disabled clave.

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 Deshabilitada o cambie el valor de la clave Deshabilitada a $False. El valor anterior de $PSDefaultParameterValues es efectivo de nuevo.

PS> $PSDefaultParameterValues.Remove("Disabled")

La siguiente sintaxis logra el mismo resultado.

PS> $PSDefaultParameterValues["Disabled"]=$False

La $PSDefaultParameterValues variable muestra la tabla hash actualizada. Cuando se usa el método Remove , la Disabled clave se quita de la salida. Si se usó la sintaxis alternativa para volver a habilitar $PSDefaultParameterValues, la Disabled clave se muestra como False.

PS> $PSDefaultParameterValues

Name                           Value
----                           -----
Disabled                       False
Get-WinEvent:LogName           Microsoft-Windows-PrintService/Operational
Get-*:Verbose                  True
Send-MailMessage:SmtpServer    ServerXYZ

Consulte también