about_Parameters

Se aplica a: Windows PowerShell 2.0, Windows PowerShell 3.0, Windows PowerShell 4.0

TEMA

about_Parameters

DESCRIPCIÓN BREVE

Describe cómo trabajar con parámetros de comando en Windows PowerShell.

DESCRIPCIÓN LARGA

La mayoría de comandos de Windows PowerShell, como los cmdlets, las funciones y los scripts, se basan en parámetros que permiten a los usuarios seleccionar opciones o proporcionar entradas. Los parámetros siguen el nombre del comando y tienen la forma siguiente:

        -<parameter_name> <parameter_value>

El nombre del parámetro está precedido por un guión (-), que indica a Windows PowerShell que la palabra que sigue el guión es un nombre de parámetro. 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 sus requisitos varían. Para obtener información sobre los parámetros de un comando, use el cmdlet Get-Help. Por ejemplo, para buscar información sobre los parámetros del cmdlet Get-ChildItem, escriba:

        Get-Help Get-ChildItem

Para obtener 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 cmdlet Get-Help devuelve diversos detalles sobre el comando, entre los que se incluyen una descripción, la sintaxis del comando, información sobre los parámetros y ejemplos que muestran cómo utilizar los parámetros en un comando.

También puede usar el parámetro Parameter del cmdlet Get-Help para buscar información sobre un parámetro determinado. O bien, puede utilizar el parámetro Parameter con el valor de carácter comodín (*) para buscar información sobre todos los parámetros del comando. Por ejemplo, el comando siguiente obtiene información sobre todos los parámetros del cmdlet Get-Member:

        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, vea 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 definir valores predeterminados personalizados, consulte about_Parameters_Default_Values.

TABLA DE ATRIBUTOS DE PARÁMETROS

Cuando se usan los parámetros Full, Parameter u Online del cmdlet Get-Help, Get-Help muestra una tabla de atributos de parámetros con información detallada sobre el parámetro.

Esta información incluye los detalles que necesita saber para utilizar el parámetro. Por ejemplo, el tema de ayuda del cmdlet Get-ChildItem 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?                    1
        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 sus atributos. En las secciones siguientes se describen los atributos del parámetro.

PARAMETER REQUIRED?

Este valor indica si el parámetro es obligatorio; es decir, si todos los comandos que utiliza este cmdlet deben incluir este parámetro. Si el valor es "True" y el parámetro no está presente en el comando, Windows PowerShell le solicita un valor para el parámetro.

PARAMETER POSITION?

Este valor indica si puede facilitar el valor de un parámetro sin que tenga que estar precedido por el nombre del parámetro. Si se establece en "0" o "named", se requiere un nombre de parámetro. Este tipo de parámetro se conoce como un parámetro con nombre. Un parámetro con nombre puede aparecer en cualquier posición después del nombre del cmdlet.

Si el valor de "Parameter position?" se establece en un entero distinto de 0, el nombre del parámetro no es necesario. Este tipo de parámetro se conoce como un 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. 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 cmdlet Get-ChildItem tiene parámetros Path y Exclude. El valor de "Parameter position?" de Path es 1, lo que significa que es un parámetro posicional. El valor de "Parameter position?" de Exclude es 0, lo que significa que es un parámetro con nombre.

Esto significa que Path no requiere el nombre del parámetro, pero su valor de parámetro debe ser el primero o el único parámetro sin nombre del comando. Sin embargo, como el parámetro Exclude es un parámetro con nombre, se puede colocar en cualquier posición del comando.

Como resultado del valor de "Parameter position?" para estos dos parámetros, puede utilizar cualquiera de los comandos siguientes:

        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 quisiera incluir otro parámetro posicional sin incluir el nombre del parámetro, ese parámetro tendría que colocarse en el orden que especifique el valor de "Parameter position?".

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 en blanco, el valor debe estar entre comillas o los espacios deben ir precedidos por el carácter de escape (`).

VALOR PREDETERMINADO

Este ajuste especifica el valor que adoptará 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 necesarios 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.

ACCEPTS MULTIPLE VALUES?

Este valor indica si un parámetro acepta varios valores de parámetro. Si 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, después, especificar la variable como valor del parámetro.

Por ejemplo, el parámetro ServiceName del cmdlet Get-Service acepta varios valores. Los dos comandos siguientes son válidos:

        get-service -servicename winrm, netlogon


        $s = "winrm", "netlogon"
        get-service -servicename $s

ACCEPTS PIPELINE INPUT?

Este valor indica si puede utilizar 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.


                             When a parameter is "True (by Value)", Windows 
                             PowerShell tries to associate any piped values 
                             with that parameter before it tries other methods
                             to interpret the command.


    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.
 
                             For example, you can pipe a value to a Name 
                             parameter only when the value has a property 
                             called "Name".

ACCEPTS WILDCARD CHARACTERS?

Este valor 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 más información sobre los parámetros comunes, consulte about_CommonParameters

VEA TAMBIÉN

about_Command_syntax

about_Comment_Based_Help

about_Functions_Advanced

about_Parameters_Default_Values

about_Pipelines

about_Wildcards