about_Parameters
Descripción breve
Describe cómo trabajar con parámetros de comando en PowerShell.
Descripción larga
La mayoría de los comandos de PowerShell, como cmdlets, funciones y scripts, dependen de parámetros para permitir a los usuarios seleccionar opciones o proporcionar entradas. Los parámetros siguen el nombre del comando y tienen el siguiente formato:
-<parameter_name> <parameter_value>
-<parameter_name>:<parameter_value>
El nombre del parámetro va precedido de un guión (-), que indica a PowerShell que la palabra que sigue al guión es un nombre de parámetro. El nombre y el valor del parámetro se pueden separar por un espacio o un carácter de dos puntos. Algunos parámetros no requieren ni aceptan un valor de parámetro. Otros parámetros requieren un valor, pero no requieren el nombre del parámetro en el comando .
El tipo de parámetros y los requisitos de esos parámetros varían. Para buscar información sobre los parámetros de un comando, use el Get-Help cmdlet . Por ejemplo, para buscar información sobre los parámetros del Get-ChildItem cmdlet, escriba:
Get-Help Get-ChildItem
Para buscar información sobre los parámetros de un script, use la ruta de acceso completa al archivo de script. Por ejemplo:
Get-Help $HOME\Documents\Scripts\Get-Function.ps1
El Get-Help cmdlet devuelve varios detalles sobre el comando, incluida una descripción, la sintaxis del comando, la información sobre los parámetros y ejemplos que muestran cómo usar los parámetros en un comando.
También puede usar el parámetro Parameter del Get-Help cmdlet para buscar información sobre un parámetro determinado. O bien, puede usar el parámetro Parameter con el carácter comodín ( * ) para buscar información sobre todos los parámetros del comando. Por ejemplo, el siguiente comando obtiene información sobre todos los parámetros del Get-Member cmdlet:
Get-Help Get-Member -Parameter *
Valores de parámetros predeterminados
Los parámetros opcionales tienen un valor predeterminado, que es el valor que se usa o se supone cuando el parámetro no se especifica en el comando.
Por ejemplo, el valor predeterminado del parámetro ComputerName de muchos cmdlets es el nombre del equipo local. Como resultado, el nombre del equipo local se usa en el comando a menos que se especifique el parámetro ComputerName .
Para buscar el valor de parámetro predeterminado, consulte el tema de ayuda del cmdlet. La descripción del parámetro debe incluir el valor predeterminado.
También puede establecer un valor predeterminado personalizado para cualquier parámetro de un cmdlet o una función avanzada. Para obtener información sobre cómo establecer valores predeterminados personalizados, consulte about_Parameters_Default_Values.
Tabla de atributos de parámetro
Cuando se usan los parámetros Full, Parameter o Online del Get-Help cmdlet, Get-Help se muestra una tabla de atributos de parámetro con información detallada sobre el parámetro.
Esta información incluye los detalles que necesita saber para usar el parámetro .
Por ejemplo, el tema de ayuda del Get-ChildItem cmdlet incluye los siguientes detalles sobre su parámetro Path:
-Path <string[]>
Specifies a path of one or more locations. Wildcard characters are
permitted. The default location is the current directory (.).
Required? false
Position? 0
Default value Current directory
Accept pipeline input? true (ByValue, ByPropertyName)
Accept wildcard characters? true
La información del parámetro incluye la sintaxis del parámetro, una descripción del parámetro y los atributos de parámetro. En las secciones siguientes se describen los atributos de parámetro.
Parámetro requerido
Esta configuración indica si el parámetro es obligatorio, es decir, si todos los comandos que usan este cmdlet deben incluir este parámetro. Cuando el valor es True y falta el parámetro del comando, PowerShell le pedirá un valor para el parámetro .
Posición del parámetro
Si la Position configuración se establece en un entero no negativo, el nombre del parámetro no es necesario. Este tipo de parámetro se conoce como parámetro posicional y el número indica la posición en la que el parámetro debe aparecer en relación con otros parámetros posicionales. Un parámetro con nombre puede aparecer en cualquier posición después del nombre del cmdlet. Si incluye el nombre del parámetro para un parámetro posicional, el parámetro puede aparecer en cualquier posición después del nombre del cmdlet.
Por ejemplo, el Get-ChildItem cmdlet tiene parámetros Path y Exclude. La Position configuración de Path es 0, lo que significa que es un parámetro posicional. La Position configuración de Exclude se denomina .
Esto significa que Path no requiere el nombre del parámetro, pero su valor de parámetro debe ser el primer valor de parámetro sin nombre en el comando. Sin embargo, dado que el parámetro Exclude es un parámetro con nombre, puede colocarlo en cualquier posición del comando.
Como resultado de la Position configuración de estos dos parámetros, puede usar cualquiera de los siguientes comandos:
Get-ChildItem -Path c:\techdocs -Exclude *.ppt
Get-ChildItem c:\techdocs -Exclude *.ppt
Get-ChildItem -Exclude *.ppt -Path c:\techdocs
Get-ChildItem -Exclude *.ppt c:\techdocs
Si tuviera que incluir otro parámetro posicional sin incluir el nombre del parámetro, ese parámetro debe colocarse en el orden especificado por la Position configuración.
Tipo de parámetro
Esta configuración especifica el tipo de Microsoft .NET Framework del valor del parámetro. Por ejemplo, si el tipo es Int32, el valor del parámetro debe ser un entero. Si el tipo es string, el valor del parámetro debe ser una cadena de caracteres.
Si la cadena contiene espacios, el valor debe incluirse entre comillas o los espacios deben ir precedidos del carácter de escape (`).
Valor predeterminado
Esta configuración especifica el valor que asume el parámetro si no se proporciona ningún otro valor. Por ejemplo, el valor predeterminado del parámetro Path suele ser el directorio actual. Los parámetros obligatorios nunca tienen un valor predeterminado. Para muchos parámetros opcionales, no hay ningún valor predeterminado porque el parámetro no tiene ningún efecto si no se usa.
Acepta varios valores
Esta configuración indica si un parámetro acepta varios valores de parámetro. Cuando un parámetro acepta varios valores, puede escribir una lista separada por comas como el valor del parámetro en el comando, o guardar una lista separada por comas (una matriz) en una variable y, a continuación, especificar la variable como valor de parámetro.
Por ejemplo, el parámetro Name del Get-Service cmdlet acepta varios valores. Los siguientes comandos son válidos:
Get-Service -Name winrm, netlogon
$s = "winrm", "netlogon"
Get-Service -Name $s
Acepta la entrada de canalización.
Esta configuración indica si puede usar el operador de canalización (|) para enviar un valor al parámetro .
Value Description
----- -----------
False Indicates that you cannot pipe a value to the
parameter.
True (by Value) Indicates that you can pipe any value to the
parameter, just so the value has the .NET
Framework type specified for the parameter or the
value can be converted to the specified .NET
Framework type.
Cuando un parámetro es "True (por valor)", PowerShell intenta asociar cualquier valor canalización con ese parámetro antes de intentar otros métodos para interpretar el comando.
True (by Property Name) Indicates that you can pipe a value to the
parameter, but the .NET Framework type of the
parameter must include a property with the same
name as the parameter.
Por ejemplo, puede canalizar un valor a un parámetro Name solo cuando el valor tiene una propiedad denominada Name.
Nota:
Un parámetro con tipo que acepta la entrada de canalización (by Value) o (by PropertyName) permite el uso de bloques de script de enlace retrasado en el parámetro .
El bloque de script delay-bind se ejecuta automáticamente durante ParameterBinding. El resultado está enlazado al parámetro . El enlace de retraso no funciona para los parámetros definidos como tipo ScriptBlock o System.Object, el bloque de script se pasa a través sin invocarse.
Puede leer sobre los bloques de scripts de enlace retrasado aquí about_Script_Blocks.md.
Acepta caracteres comodín
Esta configuración indica si el valor del parámetro puede contener caracteres comodín para que el valor del parámetro pueda coincidir con más de un elemento existente en el contenedor de destino.
Parámetros comunes
Los parámetros comunes son parámetros que puede usar con cualquier cmdlet. Para obtener más información sobre los parámetros comunes, consulte about_CommonParameters.
