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.

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.

Consulte también

• about_Command_syntax
• about_Comment_Based_Help
• about_Functions_Advanced
• about_Parameters_Default_Values
• about_Pipelines
• about_Wildcards